Hello from inside the frame!

) ``` #### Solid ```tsx import { ClientOnly } from '@ark-ui/solid/client-only' export const Basic = () => (

``` ### With Fallback **Example: with-fallback** #### React ```tsx import { ClientOnly } from '@ark-ui/react/client-only' export const WithFallback = () => ( Loading...

) ``` #### Solid ```tsx import { ClientOnly } from '@ark-ui/solid/client-only' export const WithFallback = () => ( Loading...

) ``` #### Vue ```vue ``` #### Svelte ```svelte {#snippet fallback()}

{/snippet}

``` ## API Reference **Component API Reference** #### React **ClientOnly Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `fallback` | `any` | No | | #### Solid **ClientOnly Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `fallback` | `number | boolean | Node | ArrayElement | (string & {})` | No | | #### Svelte **ClientOnly Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `fallback` | `Snippet<[]>` | No | | # Download Trigger ## Motivation The `DownloadTrigger` component provides a convenient way to programmatically trigger file downloads in web applications. It handles the complexities of downloading files, whether they are URLs, Blobs, or other data types. ## Examples ### Basic Pass the data you want to download to the `data` prop, and specify the `fileName` and `mimeType` of the file. **Example: basic** #### React ```tsx import { DownloadTrigger } from '@ark-ui/react/download-trigger' import { DownloadIcon, FileIcon } from 'lucide-react' import button from 'styles/button.module.css' import styles from 'styles/download-trigger.module.css' const content = 'Hello, World! This is a sample text file.' export const Basic = () => { return (

{content}

Download txt

) } ``` #### Solid ```tsx import { DownloadTrigger } from '@ark-ui/solid/download-trigger' import { DownloadIcon, FileIcon } from 'lucide-solid' import button from 'styles/button.module.css' import styles from 'styles/download-trigger.module.css' const content = 'Hello, World! This is a sample text file.' export const Basic = () => { return (

{content}

Download txt

``` ### Download SVG Here's an example of how to download an SVG file. **Example: svg** #### React ```tsx import { DownloadTrigger } from '@ark-ui/react/download-trigger' import { DownloadIcon, FileIcon } from 'lucide-react' import button from 'styles/button.module.css' import styles from 'styles/download-trigger.module.css' const svgContent = `` export const Svg = () => { return (

{content}

Download txt

circle.svg

Download SVG

) } ``` #### Solid ```tsx import { DownloadTrigger } from '@ark-ui/solid/download-trigger' import { DownloadIcon, FileIcon } from 'lucide-solid' import button from 'styles/button.module.css' import styles from 'styles/download-trigger.module.css' const svgContent = `` export const Svg = () => { return (

circle.svg

Download SVG

``` ### Promise You can also trigger downloads from a promise that returns a `Blob`, `File`, or `string`. **Example: with-promise** #### React ```tsx import { DownloadTrigger } from '@ark-ui/react/download-trigger' import { DownloadIcon, ImageIcon } from 'lucide-react' import button from 'styles/button.module.css' import styles from 'styles/download-trigger.module.css' export const WithPromise = () => { const fetchImage = async () => { const response = await fetch('https://picsum.photos/200/300') return response.blob() } return (

circle.svg

Download SVG

random-image.jpg (fetched on download)

Download Image

) } ``` #### Solid ```tsx import { DownloadTrigger } from '@ark-ui/solid/download-trigger' import { DownloadIcon, ImageIcon } from 'lucide-solid' import button from 'styles/button.module.css' import styles from 'styles/download-trigger.module.css' export const WithPromise = () => { const fetchImage = async () => { const response = await fetch('https://picsum.photos/200/300') return response.blob() } return (

random-image.jpg (fetched on download)

Download Image

random-image.jpg (fetched on download)

Download Image

<button onClick={() => setTrapped(false)}>End Trap</button>
        </div>
      </FocusTrap>
    </>
  )
}

```

#### Solid

```tsx
import { FocusTrap } from '@ark-ui/solid/focus-trap'
import { createSignal } from 'solid-js'

export const Basic = () => {
  const [trapped, setTrapped] = createSignal(false)
  return (
    <>
      <button onClick={() => setTrapped(true)}>Start Trap</button>
      <FocusTrap returnFocusOnDeactivate={false} disabled={!trapped()}>
        <div
          style={{
            display: 'flex',
            'flex-direction': 'column',
            gap: '1rem',
            'padding-block': '1rem',
          }}
        >
          <input type="text" placeholder="input" />
          <textarea placeholder="textarea" />
          <button onClick={() => setTrapped(false)}>End Trap</button>
        </div>
      </FocusTrap>
    </>
  )
}

```

#### Vue

```vue
<script setup lang="ts">
import { FocusTrap } from '@ark-ui/vue/focus-trap'
import { ref } from 'vue'

const trapped = ref(false)
</script>

<template>
  <button @click="trapped = true">Start Trap</button>
  <FocusTrap :return-focus-on-deactivate="false" :disabled="!trapped">
    <div style="display: flex; flex-direction: column; gap: 1rem; padding-block: 1rem">
      <input type="text" placeholder="input" />
      <textarea placeholder="textarea" />
      <button @click="trapped = false">End Trap</button>
    </div>
  </FocusTrap>
</template>

```

#### Svelte

```svelte
<script lang="ts">
  import { FocusTrap } from '@ark-ui/svelte/focus-trap'

let trapped = $state(false)
</script>

<button onclick={() => (trapped = true)}>Start Trap</button>

``` ### Autofocus The focus trap respects elements with the `autofocus` attribute. **Example: autofocus** #### React ```tsx import { FocusTrap } from '@ark-ui/react/focus-trap' import { useRef, useState } from 'react' export const Autofocus = () => { const [trapped, setTrapped] = useState(false) const toggle = () => setTrapped((c) => !c) const buttonRef = useRef(null) const getButtonNode = () => { const node = buttonRef.current if (!node) throw new Error('Button not found') return node } return (

{trapped && (

{/* biome-ignore lint/a11y/noAutofocus: intentional */}

)}

) } ``` #### Solid ```tsx import { FocusTrap } from '@ark-ui/solid/focus-trap' import { Show, createSignal } from 'solid-js' export const Autofocus = () => { const [trapped, setTrapped] = createSignal(false) let buttonRef!: HTMLButtonElement return (

``` ### Initial Focus Use the `initialFocus` prop to set the element that should receive initial focus when the trap is activated. **Example: initial-focus** #### React ```tsx import { FocusTrap } from '@ark-ui/react/focus-trap' import { useRef, useState } from 'react' export const InitialFocus = () => { const [trapped, setTrapped] = useState(false) const toggle = () => setTrapped((c) => !c) const inputRef = useRef(null) return (

{#if trapped}

{/if}

inputRef.current}>

<button onClick={() => setTrapped(false)}>End Trap</button>
        </div>
      </FocusTrap>
    </div>
  )
}

```

#### Solid

```tsx
import { FocusTrap } from '@ark-ui/solid/focus-trap'
import { createSignal } from 'solid-js'

export const InitialFocus = () => {
  const [trapped, setTrapped] = createSignal(false)
  const toggle = () => setTrapped((v) => !v)

let inputRef!: HTMLInputElement

return (
    <div>
      <button onClick={toggle}>{trapped() ? 'End Trap' : 'Start Trap'}</button>
      <FocusTrap disabled={!trapped()} initialFocus={() => inputRef}>
        <div
          style={{
            display: 'flex',
            'flex-direction': 'column',
            gap: '1rem',
            'padding-block': '1rem',
          }}
        >
          <input type="text" placeholder="First input" />
          <input ref={inputRef} type="text" placeholder="Second input (initial focus)" />
          <textarea placeholder="textarea" />
          <button onClick={toggle}>End Trap</button>
        </div>
      </FocusTrap>
    </div>
  )
}

```

#### Vue

```vue
<script setup lang="ts">
import { FocusTrap } from '@ark-ui/vue/focus-trap'
import { ref } from 'vue'

const trapped = ref(false)
const inputRef = ref<HTMLInputElement>()
const toggle = () => {
  trapped.value = !trapped.value
}
</script>

<template>
  <div>
    <button @click="toggle">{{ trapped ? 'End Trap' : 'Start Trap' }}</button>
    <FocusTrap :disabled="!trapped" :initial-focus="() => inputRef">
      <div style="display: flex; flex-direction: column; gap: 1rem; padding-block: 1rem">
        <input type="text" placeholder="First input" />
        <input ref="inputRef" type="text" placeholder="Second input (initial focus)" />
        <textarea placeholder="textarea" />
        <button @click="trapped = false">End Trap</button>
      </div>
    </FocusTrap>
  </div>
</template>

```

#### Svelte

```svelte
<script lang="ts">
  import { FocusTrap } from '@ark-ui/svelte/focus-trap'

let trapped = $state(false)
  let inputNode: HTMLInputElement | null = $state(null)

function getInputNode() {
    if (!inputNode) throw new Error('Input not found')
    return inputNode
  }
</script>

<div>
  <button onclick={() => (trapped = !trapped)}>
    {trapped ? 'End Trap' : 'Start Trap'}
  </button>
  <FocusTrap disabled={!trapped} initialFocus={getInputNode}>
    <div style="display: flex; flex-direction: column; gap: 1rem; padding-block: 1rem">
      <input type="text" placeholder="First input" />
      <input bind:this={inputNode} type="text" placeholder="Second input (initial focus)" />
      <textarea placeholder="textarea">

``` ## API Reference **Component API Reference** #### React **FocusTrap Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `disabled` | `boolean` | No | Whether the focus trap is disabled. | | `fallbackFocus` | `FocusTarget` | No | By default, an error will be thrown if the focus trap contains no elements in its tab order. With this option you can specify a fallback element to programmatically receive focus if no other tabbable elements are found. For example, you may want a popover's `

` to receive focus if the popover's content includes no tabbable elements. *Make sure the fallback element has a negative `tabindex` so it can be programmatically focused. NOTE: If `initialFocus` is `false` (or a function that returns `false`), this function will not be called when the trap is activated, and no element will be initially focused. This function may still be called while the trap is active if things change such that there are no longer any tabbable nodes in the trap. | | `initialFocus` | `VoidFunction | FocusTargetOrFalse` | No | By default, when a focus trap is activated the first element in the focus trap's tab order will receive focus. With this option you can specify a different element to receive that initial focus, or use `false` for no initially focused element at all. NOTE: Setting this option to `false` (or a function that returns `false`) will prevent the `fallbackFocus` option from being used. Setting this option to `undefined` (or a function that returns `undefined`) will result in the default behavior. | | `onActivate` | `VoidFunction` | No | A function that will be called **before** sending focus to the target element upon activation. | | `onDeactivate` | `VoidFunction` | No | A function that will be called **before** sending focus to the trigger element upon deactivation. | | `returnFocusOnDeactivate` | `boolean` | No | Default: `true`. If `false`, when the trap is deactivated, focus will *not* return to the element that had focus before activation. | | `setReturnFocus` | `type ONLY_FOR_FORMAT = | FocusTargetValueOrFalse | ((nodeFocusedBeforeActivation: HTMLElement | SVGElement) => FocusTargetValueOrFalse)` | No | By default, focus trap on deactivation will return to the element that was focused before activation. | #### Solid **FocusTrap Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `disabled` | `boolean` | No | Whether the focus trap is disabled. | | `fallbackFocus` | `FocusTarget` | No | By default, an error will be thrown if the focus trap contains no elements in its tab order. With this option you can specify a fallback element to programmatically receive focus if no other tabbable elements are found. For example, you may want a popover's `

` to receive focus if the popover's content includes no tabbable elements. *Make sure the fallback element has a negative `tabindex` so it can be programmatically focused. NOTE: If `initialFocus` is `false` (or a function that returns `false`), this function will not be called when the trap is activated, and no element will be initially focused. This function may still be called while the trap is active if things change such that there are no longer any tabbable nodes in the trap. | | `initialFocus` | `VoidFunction | FocusTargetOrFalse` | No | By default, when a focus trap is activated the first element in the focus trap's tab order will receive focus. With this option you can specify a different element to receive that initial focus, or use `false` for no initially focused element at all. NOTE: Setting this option to `false` (or a function that returns `false`) will prevent the `fallbackFocus` option from being used. Setting this option to `undefined` (or a function that returns `undefined`) will result in the default behavior. | | `onActivate` | `VoidFunction` | No | A function that will be called **before** sending focus to the target element upon activation. | | `onDeactivate` | `VoidFunction` | No | A function that will be called **before** sending focus to the trigger element upon deactivation. | | `returnFocusOnDeactivate` | `boolean` | No | Default: `true`. If `false`, when the trap is deactivated, focus will *not* return to the element that had focus before activation. | | `setReturnFocus` | `type ONLY_FOR_FORMAT = | FocusTargetValueOrFalse | ((nodeFocusedBeforeActivation: HTMLElement | SVGElement) => FocusTargetValueOrFalse)` | No | By default, focus trap on deactivation will return to the element that was focused before activation. | #### Vue **FocusTrap Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `disabled` | `boolean` | No | Whether the focus trap is disabled | | `fallbackFocus` | `FocusTarget` | No | Element to focus if initialFocus is not found. By default, focuses on container element | | `initialFocus` | `FocusTargetOrFalse | VoidFunction` | No | Element to focus when trap is activated. By default, focuses on first tabbable element | | `returnFocusOnDeactivate` | `boolean` | No | Whether to return focus to the element that had focus when trap was activated | | `setReturnFocus` | `FocusTargetValueOrFalse | ((node: FocusableElement) => FocusTargetValueOrFalse)` | No | Custom element to return focus to when trap is deactivated | #### Svelte **FocusTrap Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `disabled` | `boolean` | No | Whether the focus trap is disabled. | | `fallbackFocus` | `FocusTarget` | No | By default, an error will be thrown if the focus trap contains no elements in its tab order. With this option you can specify a fallback element to programmatically receive focus if no other tabbable elements are found. For example, you may want a popover's `

File size

) } ``` ### Sizes Use the `sizes` prop to specify custom byte sizes for formatting. ```tsx import { Format } from '@ark-ui/react/format' import styles from 'styles/format.module.css' export const ByteSizes = () => { const byteSizes = [50, 5000, 5000000, 5000000000] return (

{byteSizes.map((size) => (

))}

) } ``` ### Locale Use the `locale` prop to format the byte value according to a specific locale. ```tsx import { Format } from '@ark-ui/react/format' import { LocaleProvider } from '@ark-ui/react/locale' import styles from 'styles/format.module.css' export const ByteWithLocale = () => { const locales = ['de-DE', 'zh-CN'] return (

{locales.map((locale) => (

{locale}:

))}

) } ``` ### Unit Use the `unit` prop to specify the unit of the byte value. ```tsx import { Format } from '@ark-ui/react/format' import styles from 'styles/format.module.css' export const ByteWithUnit = () => { return (

File size:

) } ``` ### Unit Display Use the `unitDisplay` prop to specify the display of the unit. ```tsx import { Format } from '@ark-ui/react/format' import styles from 'styles/format.module.css' export const ByteWithUnitDisplay = () => { const unitDisplays = ['narrow', 'short', 'long'] as const return (

{unitDisplays.map((unitDisplay) => (

{unitDisplay}:

))}

) } ``` ### Unit System Use the `unitSystem` prop to specify whether to use decimal (1000 bytes) or binary (1024 bytes) unit system. ```tsx import { Format } from '@ark-ui/react/format' import styles from 'styles/format.module.css' export const ByteWithUnitSystem = () => { return (

Decimal (1000 bytes):

Binary (1024 bytes):

) } ``` # Format Relative Time ## Usage The relative time formatting logic is handled by the native `Intl.RelativeTimeFormat` API and smartly cached to avoid performance issues when using the same locale and options. ```jsx import { Format } from '@ark-ui/react' ``` ## Examples ### Basic Use the `Format.RelativeTime` component to format a relative time with default options. ```tsx import { Format } from '@ark-ui/react/format' import styles from 'styles/format.module.css' export const RelativeTimeBasic = () => { return (

Last updated

) } ``` ### Short Use the `style="short"` prop to format the relative time in short format. ```tsx import { Format } from '@ark-ui/react/format' import styles from 'styles/format.module.css' export const RelativeTimeShort = () => { return (

Edited

) } ``` # Frame ## Usage The `Frame` component is used to render a component in an iframe. - Tracks the size of the content and exposes them via css variables. - Support for `head` prop to inject scripts and styles. - Support for mount and unmount callbacks. ```jsx import { Frame } from '@ark-ui/react' ``` ## Examples ### Basic Wrap your component in the `Frame` component to render it in an iframe. ```tsx import { Frame } from '@ark-ui/react/frame' export const Basic = () => { return ( {'body { background-color: #f0f0f0; }'}} >

Hello from inside the frame!

This content is rendered within our custom frame component using a Portal.

) } ``` ### Injecting Script Using the `onMount` prop, you can inject a script into the iframe. ```tsx import { Frame } from '@ark-ui/react/frame' import { useRef } from 'react' export const Script = () => { const ref = useRef(null) return ( { const doc = ref.current?.contentDocument if (!doc) return const script = doc.createElement('script') script.innerHTML = 'console.log("Hello from inside the frame!")' doc.body.appendChild(script) }} style={{ border: '1px solid #ccc', width: '100%', height: 'var(--height)' }} >

Hello from inside the frame!

This content is rendered within our custom frame component using a Portal.

) } ``` ### Custom src doc Use the `srcDoc` prop to specify the HTML content of the page to use in the iframe. ```tsx import { Frame } from '@ark-ui/react/frame' const srcDoc = `

` export const SrcDoc = () => { return (

Hello from inside the frame!

This content is rendered within our custom frame component using a Portal.

The frame has custom initial content, including Font Awesome and Open Sans font.

) } ``` ## API Reference ### Props **Component API Reference** #### React **Frame Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `head` | `string | number | bigint | boolean | ReactElement> | Iterable | ReactPortal | Promise<...>` | No | Additional content to be inserted into the frame's | | `onMount` | `() => void` | No | Callback function to be executed when the frame is mounted | | `onUnmount` | `() => void` | No | Callback function to be executed when the frame is unmounted | #### Solid **Frame Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `head` | `number | boolean | Node | ArrayElement | (string & {})` | No | Additional content to be inserted into the frame's | | `onMount` | `() => void` | No | Callback function to be executed when the frame is mounted | | `onUnmount` | `() => void` | No | Callback function to be executed when the frame is unmounted | #### Vue **Frame Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `head` | `VNode | VNode[]` | No | | | `srcDoc` | `string` | No | | #### Svelte **Frame Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `head` | `Snippet<[]>` | No | Additional content to be inserted into the frame's | | `onMount` | `() => void` | No | Callback function to be executed when the frame is mounted | | `onUnmount` | `() => void` | No | Callback function to be executed when the frame is unmounted | | `ref` | `HTMLIFrameElement` | No | The bindable ref of the iframe | | `srcdoc` | `string` | No | The source document to be displayed in the frame | # Highlight ## Usage The Highlight component takes a `text` prop containing the full text and a `query` prop specifying the text to highlight. It then renders the text with highlighted portions wrapped in `` tags. **Example: basic** #### React ```tsx import { Highlight } from '@ark-ui/react/highlight' import styles from 'styles/highlight.module.css' export const Basic = () => (

) ``` #### Solid ```tsx import { Highlight } from '@ark-ui/solid/highlight' import styles from 'styles/highlight.module.css' export const Basic = () => (

``` ### Dynamic Query Control the `query` prop with state to create an interactive search highlighting experience. **Example: dynamic-query** #### React ```tsx import { Highlight } from '@ark-ui/react/highlight' import { useState } from 'react' import field from 'styles/field.module.css' import styles from 'styles/highlight.module.css' export const DynamicQuery = () => { const [query, setQuery] = useState('component') return (

setQuery(e.target.value)} />

) } ``` #### Solid ```tsx import { Highlight } from '@ark-ui/solid/highlight' import { createSignal } from 'solid-js' import field from 'styles/field.module.css' import styles from 'styles/highlight.module.css' export const DynamicQuery = () => { const [query, setQuery] = createSignal('component') return (

setQuery(e.target.value)} />

``` ### Multiple Queries You can highlight multiple terms by passing an array of strings to the `query` prop. **Example: multiple** #### React ```tsx import { Highlight } from '@ark-ui/react/highlight' import styles from 'styles/highlight.module.css' export const Multiple = () => (

) ``` #### Solid ```tsx import { Highlight } from '@ark-ui/solid/highlight' import styles from 'styles/highlight.module.css' export const Multiple = () => (

``` ### Case Sensitivity By default, the highlighting is case-sensitive. Use the `ignoreCase` prop to make it case-insensitive. **Example: ignore-case** #### React ```tsx import { Highlight } from '@ark-ui/react/highlight' import styles from 'styles/highlight.module.css' export const IgnoreCase = () => (

) ``` #### Solid ```tsx import { Highlight } from '@ark-ui/solid/highlight' import styles from 'styles/highlight.module.css' export const IgnoreCase = () => (

``` ### Match All By default, the Highlight component matches the first occurrence of the query. To highlight all occurrences of the query, set the `matchAll` prop to `true`. **Example: match-all** #### React ```tsx import { Highlight } from '@ark-ui/react/highlight' import styles from 'styles/highlight.module.css' export const MatchAll = () => (

Match All

Match First Only

) ``` #### Solid ```tsx import { Highlight } from '@ark-ui/solid/highlight' import styles from 'styles/highlight.module.css' export const MatchAll = () => (

Match All

Match First Only

``` ### Exact Match By default, the Highlight component matches partial words. Use the `exactMatch` prop to only highlight whole words that match the query exactly. **Example: exact-match** #### React ```tsx import { Highlight } from '@ark-ui/react/highlight' import styles from 'styles/highlight.module.css' export const ExactMatch = () => (

Match All

Match First Only

Partial Match

Exact Match

) ``` #### Solid ```tsx import { Highlight } from '@ark-ui/solid/highlight' import styles from 'styles/highlight.module.css' export const ExactMatch = () => (

Partial Match

Exact Match