- ` or `
- ` elements correctly within `
- ` or `
- ` elements correctly within `
- ` or `
- Click to select single item
- Ctrl/Cmd + Click to toggle individual items
- Shift + Click to select range from first selected item
- Click to select single item
- Ctrl/Cmd + Click to toggle individual items
- Shift + Click to select range from first selected item
- Click to select single item
- Ctrl/Cmd + Click to toggle individual items
- Shift + Click to select range from first selected item
- Click to select single item
- Ctrl/Cmd + Click to toggle individual items
- Shift + Click to select range from first selected item
- {log} {/each}
- ({
initialItems: [
{ label: 'React', value: 'react' },
{ label: 'Solid', value: 'solid' },
{ label: 'Vue', value: 'vue' },
{ label: 'Svelte', value: 'svelte' },
],
filter: contains,
})
const isValidNewOption = (inputValue: string) => {
const exactOptionMatch = collection.filter((item) => item.toLowerCase() === inputValue.toLowerCase()).size > 0
return !exactOptionMatch && inputValue.trim().length > 0
}
const [selectedValue, setSelectedValue] = useState
Open Clear Frameworks {collection.items.map((item) => ({isNewOptionValue(item.value) ? ( ))}+ Create "{item.label}" ) : ({item.label} {item.__new__ ? NEW_OPTION_VALUE : ''} )}✓ - ({ initialItems: [ { label: 'React', value: 'react' }, { label: 'Solid', value: 'solid' }, { label: 'Vue', value: 'vue' }, { label: 'Svelte', value: 'svelte' }, ], filter: filterFn().contains, }) const isValidNewOption = (inputValue: string) => { const exactOptionMatch = collection().items.filter((item) => item.label.toLowerCase() === inputValue.toLowerCase()).length > 0 return !exactOptionMatch && inputValue.trim().length > 0 } const [selectedValue, setSelectedValue] = createSignal
Open Clear Frameworks {(item) => ( {isNewOptionValue(item.value) ? ( )}+ Create "{item.label}" ) : ({item.label} {item.__new__ ? NEW_OPTION_VALUE : ''} )}✓ Open Clear Frameworks + Create "{{ item.label }}" {{ item.label }} {{ item.__new__ ? NEW_OPTION_VALUE : '' }} ✓ Open Clear Frameworks {#each collection().items as item (item.value)}{#if isNewOptionValue(item.value)} {/each}+ Create "{item.label}" {:else}{item.label} {item.__new__ ? NEW_OPTION_VALUE : ''} {/if}✓ Open Clear Frameworks {collection.items.map((item) => ({item.country} ✓ Open Clear Countries {(item) => ( {item.country} ✓ Open Clear Countries {{ item.country }} ✓ Open Clear Countries {#each collection().items as item (item.code)}{item.country} ✓ { navigate({ to: e.node.href }) }} > {/* ... */} ) } ``` ### Custom Objects By default, the combobox collection expects an array of objects with `label` and `value` properties. In some cases, you may need to deal with custom objects. Use the `itemToString` and `itemToValue` props to map the custom object to the required interface. ```tsx const items = [ { country: 'United States', code: 'US', flag: '🇺🇸' }, { country: 'Canada', code: 'CA', flag: '🇨🇦' }, { country: 'Australia', code: 'AU', flag: '🇦🇺' }, // ... ] const { collection } = useListCollection({ initialItems: items, itemToString: (item) => item.country, itemToValue: (item) => item.code, }) ``` ### Type-Safety The `Combobox.RootComponent` type enables you to create closed, strongly typed wrapper components that maintain full type safety for collection items. This is particularly useful when building reusable combobox components with custom props and consistent styling. ```tsx import { Combobox as ArkCombobox, type CollectionItem } from '@ark-ui/react/combobox' import { useListCollection } from '@ark-ui/react/collection' interface ComboboxPropsextends ArkCombobox.RootProps {} const Combobox: ArkCombobox.RootComponent = (props) => { return {/* ... */} } ``` Then, you can use the `Combobox` component as follows: ```tsx const App = () => { const { collection } = useListCollection({ initialItems: [ { label: 'React', value: 'react' }, { label: 'Vue', value: 'vue' }, { label: 'Svelte', value: 'svelte' }, ], }) return ({ // this will be strongly typed Array<{ label: string, value: string }> console.log(e.items) }} > {/* ... */} ) } ``` ### Limit Large Datasets The recommended way of managing large lists is to use the `limit` property on the `useListCollection` hook. This will limit the number of rendered items in the DOM to improve performance. ```tsx {3} const { collection } = useListCollection({ initialItems: items, limit: 10, }) ``` ### Available height and width The following css variables are exposed to the `Combobox.Positioner` which you can use to style the `Combobox.Content` ```css /* width of the combobox control */ --reference-width:; /* width of the available viewport */ --available-width: ; /* height of the available viewport */ --available-height: ; ``` For example, if you want to make sure the maximum height doesn't exceed the available height, you can use the following: ```css [data-scope='combobox'][data-part='content'] { max-height: calc(var(--available-height) - 100px); } ``` ## API Reference ### Props **Component API Reference** #### React **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `collection` | `ListCollection ` | Yes | The collection of items | | `allowCustomValue` | `boolean` | No | Whether to allow typing custom values in the input | | `alwaysSubmitOnEnter` | `boolean` | No | Whether to always submit on Enter key press, even if popup is open. Useful for single-field autocomplete forms where Enter should submit the form. | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `autoFocus` | `boolean` | No | Whether to autofocus the input on mount | | `closeOnSelect` | `boolean` | No | Whether to close the combobox when an item is selected. | | `composite` | `boolean` | No | Whether the combobox is a composed with other composite widgets like tabs | | `defaultHighlightedValue` | `string` | No | The initial highlighted value of the combobox when rendered. Use when you don't need to control the highlighted value of the combobox. | | `defaultInputValue` | `string` | No | The initial value of the combobox's input when rendered. Use when you don't need to control the value of the combobox's input. | | `defaultOpen` | `boolean` | No | The initial open state of the combobox when rendered. Use when you don't need to control the open state of the combobox. | | `defaultValue` | `string[]` | No | The initial value of the combobox's selected items when rendered. Use when you don't need to control the value of the combobox's selected items. | | `disabled` | `boolean` | No | Whether the combobox is disabled | | `disableLayer` | `boolean` | No | Whether to disable registering this a dismissable layer | | `form` | `string` | No | The associate form of the combobox. | | `highlightedValue` | `string` | No | The controlled highlighted value of the combobox | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string label: string control: string input: string content: string trigger: string clearTrigger: string item: (id: string, index?: number | undefined) => string positioner: string itemGroup: (id: string | number) => string itemGroupLabel: (id: string | number) => string }>` | No | The ids of the elements in the combobox. Useful for composition. | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `inputBehavior` | `'none' | 'autohighlight' | 'autocomplete'` | No | Defines the auto-completion behavior of the combobox. - `autohighlight`: The first focused item is highlighted as the user types - `autocomplete`: Navigating the listbox with the arrow keys selects the item and the input is updated | | `inputValue` | `string` | No | The controlled value of the combobox's input | | `invalid` | `boolean` | No | Whether the combobox is invalid | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `loopFocus` | `boolean` | No | Whether to loop the keyboard navigation through the items | | `multiple` | `boolean` | No | Whether to allow multiple selection. **Good to know:** When `multiple` is `true`, the `selectionBehavior` is automatically set to `clear`. It is recommended to render the selected items in a separate container. | | `name` | `string` | No | The `name` attribute of the combobox's input. Useful for form submission | | `navigate` | `(details: NavigateDetails) => void` | No | Function to navigate to the selected item | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component | | `onHighlightChange` | `(details: HighlightChangeDetails ) => void` | No | Function called when an item is highlighted using the pointer or keyboard navigation. | | `onInputValueChange` | `(details: InputValueChangeDetails) => void` | No | Function called when the input's value changes | | `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component | | `onOpenChange` | `(details: OpenChangeDetails) => void` | No | Function called when the popup is opened | | `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component | | `onSelect` | `(details: SelectionDetails) => void` | No | Function called when an item is selected | | `onValueChange` | `(details: ValueChangeDetails ) => void` | No | Function called when a new item is selected | | `open` | `boolean` | No | The controlled open state of the combobox | | `openOnChange` | `boolean | ((details: InputValueChangeDetails) => boolean)` | No | Whether to show the combobox when the input value changes | | `openOnClick` | `boolean` | No | Whether to open the combobox popup on initial click on the input | | `openOnKeyPress` | `boolean` | No | Whether to open the combobox on arrow key press | | `placeholder` | `string` | No | The placeholder text of the combobox's input | | `positioning` | `PositioningOptions` | No | The positioning options to dynamically position the menu | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `readOnly` | `boolean` | No | Whether the combobox is readonly. This puts the combobox in a "non-editable" mode but the user can still interact with it | | `required` | `boolean` | No | Whether the combobox is required | | `scrollToIndexFn` | `(details: ScrollToIndexDetails) => void` | No | Function to scroll to a specific index | | `selectionBehavior` | `'clear' | 'replace' | 'preserve'` | No | The behavior of the combobox input when an item is selected - `replace`: The selected item string is set as the input value - `clear`: The input value is cleared - `preserve`: The input value is preserved | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | | `value` | `string[]` | No | The controlled value of the combobox's selected items | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | root | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **ClearTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ClearTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | clear-trigger | | `[data-invalid]` | Present when invalid | **Content Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Content Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | content | | `[data-state]` | "open" | "closed" | | `[data-nested]` | listbox | | `[data-has-nested]` | listbox | | `[data-placement]` | The placement of the content | | `[data-empty]` | Present when the content is empty | **Control Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Control Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | control | | `[data-state]` | "open" | "closed" | | `[data-focus]` | Present when focused | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | **Empty Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | input | | `[data-invalid]` | Present when invalid | | `[data-autofocus]` | | | `[data-state]` | "open" | "closed" | **ItemGroupLabel Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemGroup Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemGroup Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | item-group | | `[data-empty]` | Present when the content is empty | **ItemIndicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemIndicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | item-indicator | | `[data-state]` | "checked" | "unchecked" | **Item Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `item` | `any` | No | The item to render | | `persistFocus` | `boolean` | No | Whether hovering outside should clear the highlighted state | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | item | | `[data-highlighted]` | Present when highlighted | | `[data-state]` | "checked" | "unchecked" | | `[data-disabled]` | Present when disabled | | `[data-value]` | The value of the item | **ItemText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | item-text | | `[data-state]` | "checked" | "unchecked" | | `[data-disabled]` | Present when disabled | | `[data-highlighted]` | Present when highlighted | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | label | | `[data-readonly]` | Present when read-only | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-required]` | Present when required | | `[data-focus]` | Present when focused | **List Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **List Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | list | | `[data-empty]` | Present when the content is empty | **Positioner Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseComboboxReturn ` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `focusable` | `boolean` | No | Whether the trigger is focusable | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | trigger | | `[data-state]` | "open" | "closed" | | `[data-invalid]` | Present when invalid | | `[data-focusable]` | | | `[data-readonly]` | Present when read-only | | `[data-disabled]` | Present when disabled | #### Solid **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `collection` | `ListCollection ` | Yes | The collection of items | | `allowCustomValue` | `boolean` | No | Whether to allow typing custom values in the input | | `alwaysSubmitOnEnter` | `boolean` | No | Whether to always submit on Enter key press, even if popup is open. Useful for single-field autocomplete forms where Enter should submit the form. | | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `autoFocus` | `boolean` | No | Whether to autofocus the input on mount | | `closeOnSelect` | `boolean` | No | Whether to close the combobox when an item is selected. | | `composite` | `boolean` | No | Whether the combobox is a composed with other composite widgets like tabs | | `defaultHighlightedValue` | `string` | No | The initial highlighted value of the combobox when rendered. Use when you don't need to control the highlighted value of the combobox. | | `defaultInputValue` | `string` | No | The initial value of the combobox's input when rendered. Use when you don't need to control the value of the combobox's input. | | `defaultOpen` | `boolean` | No | The initial open state of the combobox when rendered. Use when you don't need to control the open state of the combobox. | | `defaultValue` | `string[]` | No | The initial value of the combobox's selected items when rendered. Use when you don't need to control the value of the combobox's selected items. | | `disabled` | `boolean` | No | Whether the combobox is disabled | | `disableLayer` | `boolean` | No | Whether to disable registering this a dismissable layer | | `form` | `string` | No | The associate form of the combobox. | | `highlightedValue` | `string` | No | The controlled highlighted value of the combobox | | `ids` | `Partial<{ root: string label: string control: string input: string content: string trigger: string clearTrigger: string item: (id: string, index?: number | undefined) => string positioner: string itemGroup: (id: string | number) => string itemGroupLabel: (id: string | number) => string }>` | No | The ids of the elements in the combobox. Useful for composition. | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `inputBehavior` | `'none' | 'autohighlight' | 'autocomplete'` | No | Defines the auto-completion behavior of the combobox. - `autohighlight`: The first focused item is highlighted as the user types - `autocomplete`: Navigating the listbox with the arrow keys selects the item and the input is updated | | `inputValue` | `string` | No | The controlled value of the combobox's input | | `invalid` | `boolean` | No | Whether the combobox is invalid | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `loopFocus` | `boolean` | No | Whether to loop the keyboard navigation through the items | | `multiple` | `boolean` | No | Whether to allow multiple selection. **Good to know:** When `multiple` is `true`, the `selectionBehavior` is automatically set to `clear`. It is recommended to render the selected items in a separate container. | | `name` | `string` | No | The `name` attribute of the combobox's input. Useful for form submission | | `navigate` | `(details: NavigateDetails) => void` | No | Function to navigate to the selected item | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component | | `onHighlightChange` | `(details: HighlightChangeDetails ) => void` | No | Function called when an item is highlighted using the pointer or keyboard navigation. | | `onInputValueChange` | `(details: InputValueChangeDetails) => void` | No | Function called when the input's value changes | | `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component | | `onOpenChange` | `(details: OpenChangeDetails) => void` | No | Function called when the popup is opened | | `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component | | `onSelect` | `(details: SelectionDetails) => void` | No | Function called when an item is selected | | `onValueChange` | `(details: ValueChangeDetails ) => void` | No | Function called when a new item is selected | | `open` | `boolean` | No | The controlled open state of the combobox | | `openOnChange` | `boolean | ((details: InputValueChangeDetails) => boolean)` | No | Whether to show the combobox when the input value changes | | `openOnClick` | `boolean` | No | Whether to open the combobox popup on initial click on the input | | `openOnKeyPress` | `boolean` | No | Whether to open the combobox on arrow key press | | `placeholder` | `string` | No | The placeholder text of the combobox's input | | `positioning` | `PositioningOptions` | No | The positioning options to dynamically position the menu | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `readOnly` | `boolean` | No | Whether the combobox is readonly. This puts the combobox in a "non-editable" mode but the user can still interact with it | | `required` | `boolean` | No | Whether the combobox is required | | `scrollToIndexFn` | `(details: ScrollToIndexDetails) => void` | No | Function to scroll to a specific index | | `selectionBehavior` | `'replace' | 'clear' | 'preserve'` | No | The behavior of the combobox input when an item is selected - `replace`: The selected item string is set as the input value - `clear`: The input value is cleared - `preserve`: The input value is preserved | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | | `value` | `string[]` | No | The controlled value of the combobox's selected items | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | root | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **ClearTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ClearTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | clear-trigger | | `[data-invalid]` | Present when invalid | **Content 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. | **Content Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | content | | `[data-state]` | "open" | "closed" | | `[data-nested]` | listbox | | `[data-has-nested]` | listbox | | `[data-placement]` | The placement of the content | | `[data-empty]` | Present when the content is empty | **Control 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. | **Control Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | control | | `[data-state]` | "open" | "closed" | | `[data-focus]` | Present when focused | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | **Empty 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. | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'input'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | input | | `[data-invalid]` | Present when invalid | | `[data-autofocus]` | | | `[data-state]` | "open" | "closed" | **ItemGroupLabel 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. | **ItemGroup 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. | **ItemGroup Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | item-group | | `[data-empty]` | Present when the content is empty | **ItemIndicator 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. | **ItemIndicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | item-indicator | | `[data-state]` | "checked" | "unchecked" | **Item 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. | | `item` | `any` | No | The item to render | | `persistFocus` | `boolean` | No | Whether hovering outside should clear the highlighted state | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | item | | `[data-highlighted]` | Present when highlighted | | `[data-state]` | "checked" | "unchecked" | | `[data-disabled]` | Present when disabled | | `[data-value]` | The value of the item | **ItemText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'span'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | item-text | | `[data-state]` | "checked" | "unchecked" | | `[data-disabled]` | Present when disabled | | `[data-highlighted]` | Present when highlighted | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'label'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | label | | `[data-readonly]` | Present when read-only | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-required]` | Present when required | | `[data-focus]` | Present when focused | **List 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. | **List Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | list | | `[data-empty]` | Present when the content is empty | **Positioner 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. | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseComboboxReturn ` | Yes | | | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `focusable` | `boolean` | No | Whether the trigger is focusable | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | trigger | | `[data-state]` | "open" | "closed" | | `[data-invalid]` | Present when invalid | | `[data-focusable]` | | | `[data-readonly]` | Present when read-only | | `[data-disabled]` | Present when disabled | #### Vue **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `allowCustomValue` | `boolean` | No | Whether to allow typing custom values in the input | | `alwaysSubmitOnEnter` | `boolean` | No | Whether to allow bypassing the default two-step behavior (Enter to close combobox, then Enter to submit form) and instead submit the form immediately on Enter press. This is useful for single-field autocomplete forms where Enter should submit the form directly. | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `autoFocus` | `boolean` | No | Whether to autofocus the input on mount | | `closeOnSelect` | `boolean` | No | Whether to close the combobox when an item is selected. | | `collection` | `ListCollection ` | No | The collection of items | | `composite` | `boolean` | No | Whether the combobox is a composed with other composite widgets like tabs | | `defaultHighlightedValue` | `string` | No | The initial highlighted value of the combobox when rendered. Use when you don't need to control the highlighted value of the combobox. | | `defaultInputValue` | `string` | No | The initial value of the combobox's input when rendered. Use when you don't need to control the value of the combobox's input. | | `defaultOpen` | `boolean` | No | The initial open state of the combobox when rendered. Use when you don't need to control the open state of the combobox. | | `defaultValue` | `string[]` | No | The initial value of the combobox's selected items when rendered. Use when you don't need to control the value of the combobox's selected items. | | `disabled` | `boolean` | No | Whether the combobox is disabled | | `disableLayer` | `boolean` | No | Whether to disable registering this a dismissable layer | | `form` | `string` | No | The associate form of the combobox. | | `highlightedValue` | `string` | No | The controlled highlighted value of the combobox | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string label: string control: string input: string content: string trigger: string clearTrigger: string item(id: string, index?: number | undefined): string positioner: string itemGroup(id: string | number): string itemGroupLabel(id: string | number): string }>` | No | The ids of the elements in the combobox. Useful for composition. | | `inputBehavior` | `'none' | 'autohighlight' | 'autocomplete'` | No | Defines the auto-completion behavior of the combobox. - `autohighlight`: The first focused item is highlighted as the user types - `autocomplete`: Navigating the listbox with the arrow keys selects the item and the input is updated | | `inputValue` | `string` | No | The controlled value of the combobox's input | | `invalid` | `boolean` | No | Whether the combobox is invalid | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `loopFocus` | `boolean` | No | Whether to loop the keyboard navigation through the items | | `modelValue` | `string[]` | No | The v-model value of the combobox | | `multiple` | `boolean` | No | Whether to allow multiple selection. **Good to know:** When `multiple` is `true`, the `selectionBehavior` is automatically set to `clear`. It is recommended to render the selected items in a separate container. | | `name` | `string` | No | The `name` attribute of the combobox's input. Useful for form submission | | `navigate` | `(details: NavigateDetails) => void` | No | Function to navigate to the selected item | | `open` | `boolean` | No | The controlled open state of the combobox | | `openOnChange` | `boolean | ((details: InputValueChangeDetails) => boolean)` | No | Whether to show the combobox when the input value changes | | `openOnClick` | `boolean` | No | Whether to open the combobox popup on initial click on the input | | `openOnKeyPress` | `boolean` | No | Whether to open the combobox on arrow key press | | `placeholder` | `string` | No | The placeholder text of the combobox's input | | `positioning` | `PositioningOptions` | No | The positioning options to dynamically position the menu | | `readOnly` | `boolean` | No | Whether the combobox is readonly. This puts the combobox in a "non-editable" mode but the user can still interact with it | | `required` | `boolean` | No | Whether the combobox is required | | `scrollToIndexFn` | `(details: ScrollToIndexDetails) => void` | No | Function to scroll to a specific index | | `selectionBehavior` | `'clear' | 'replace' | 'preserve'` | No | The behavior of the combobox input when an item is selected - `replace`: The selected item string is set as the input value - `clear`: The input value is cleared - `preserve`: The input value is preserved | | `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | root | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **ClearTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ClearTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | clear-trigger | | `[data-invalid]` | Present when invalid | **Content Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Content Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | content | | `[data-state]` | "open" | "closed" | | `[data-nested]` | listbox | | `[data-has-nested]` | listbox | | `[data-placement]` | The placement of the content | | `[data-empty]` | Present when the content is empty | **Control Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Control Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | control | | `[data-state]` | "open" | "closed" | | `[data-focus]` | Present when focused | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | **Empty Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | input | | `[data-invalid]` | Present when invalid | | `[data-autofocus]` | | | `[data-state]` | "open" | "closed" | **ItemGroupLabel Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemGroup Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `id` | `string` | No | | **ItemGroup Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | item-group | | `[data-empty]` | Present when the content is empty | **ItemIndicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemIndicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | item-indicator | | `[data-state]` | "checked" | "unchecked" | **Item Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `item` | `any` | No | The item to render | | `persistFocus` | `boolean` | No | Whether hovering outside should clear the highlighted state | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | item | | `[data-highlighted]` | Present when highlighted | | `[data-state]` | "checked" | "unchecked" | | `[data-disabled]` | Present when disabled | | `[data-value]` | The value of the item | **ItemText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | item-text | | `[data-state]` | "checked" | "unchecked" | | `[data-disabled]` | Present when disabled | | `[data-highlighted]` | Present when highlighted | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | label | | `[data-readonly]` | Present when read-only | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-required]` | Present when required | | `[data-focus]` | Present when focused | **List Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **List Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | list | | `[data-empty]` | Present when the content is empty | **Positioner Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `ComboboxApi ) => void` | No | Function called when an item is highlighted using the pointer or keyboard navigation. | | `onInputValueChange` | `(details: InputValueChangeDetails) => void` | No | Function called when the input's value changes | | `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component | | `onOpenChange` | `(details: OpenChangeDetails) => void` | No | Function called when the popup is opened | | `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component | | `onSelect` | `(details: SelectionDetails) => void` | No | Function called when an item is selected | | `onValueChange` | `(details: ValueChangeDetails ) => void` | No | Function called when a new item is selected | | `open` | `boolean` | No | The controlled open state of the combobox | | `openOnChange` | `boolean | ((details: InputValueChangeDetails) => boolean)` | No | Whether to show the combobox when the input value changes | | `openOnClick` | `boolean` | No | Whether to open the combobox popup on initial click on the input | | `openOnKeyPress` | `boolean` | No | Whether to open the combobox on arrow key press | | `placeholder` | `string` | No | The placeholder text of the combobox's input | | `positioning` | `PositioningOptions` | No | The positioning options to dynamically position the menu | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `readOnly` | `boolean` | No | Whether the combobox is readonly. This puts the combobox in a "non-editable" mode but the user can still interact with it | | `ref` | `Element` | No | | | `required` | `boolean` | No | Whether the combobox is required | | `scrollToIndexFn` | `(details: ScrollToIndexDetails) => void` | No | Function to scroll to a specific index | | `selectionBehavior` | `'replace' | 'clear' | 'preserve'` | No | The behavior of the combobox input when an item is selected - `replace`: The selected item string is set as the input value - `clear`: The input value is cleared - `preserve`: The input value is preserved | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | | `value` | `string[]` | No | The controlled value of the combobox's selected items | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | root | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **ClearTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **ClearTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | clear-trigger | | `[data-invalid]` | Present when invalid | **Content 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. | | `ref` | `Element` | No | | **Content Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | content | | `[data-state]` | "open" | "closed" | | `[data-nested]` | listbox | | `[data-has-nested]` | listbox | | `[data-placement]` | The placement of the content | | `[data-empty]` | Present when the content is empty | **Context Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `render` | `Snippet<[UseComboboxContext ]>` | Yes | | **Control 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. | | `ref` | `Element` | No | | **Control Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | control | | `[data-state]` | "open" | "closed" | | `[data-focus]` | Present when focused | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | **Empty 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. | | `ref` | `Element` | No | | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'input'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Input Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | input | | `[data-invalid]` | Present when invalid | | `[data-autofocus]` | | | `[data-state]` | "open" | "closed" | **ItemContext Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `render` | `Snippet<[UseComboboxItemContext]>` | Yes | | **ItemGroupLabel 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. | | `ref` | `Element` | No | | **ItemGroup 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. | | `id` | `string` | No | | | `ref` | `Element` | No | | **ItemGroup Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | item-group | | `[data-empty]` | Present when the content is empty | **ItemIndicator 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. | | `ref` | `Element` | No | | **ItemIndicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | item-indicator | | `[data-state]` | "checked" | "unchecked" | **Item 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. | | `item` | `{}` | No | | | `persistFocus` | `boolean` | No | | | `ref` | `Element` | No | | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | item | | `[data-highlighted]` | Present when highlighted | | `[data-state]` | "checked" | "unchecked" | | `[data-disabled]` | Present when disabled | | `[data-value]` | The value of the item | **ItemText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **ItemText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | item-text | | `[data-state]` | "checked" | "unchecked" | | `[data-disabled]` | Present when disabled | | `[data-highlighted]` | Present when highlighted | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'label'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | label | | `[data-readonly]` | Present when read-only | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-required]` | Present when required | | `[data-focus]` | Present when focused | **List 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. | | `ref` | `Element` | No | | **List Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | list | | `[data-empty]` | Present when the content is empty | **Positioner 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. | | `ref` | `Element` | No | | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseComboboxReturn ` | Yes | | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `ref` | `Element` | No | | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | combobox | | `[data-part]` | trigger | | `[data-state]` | "open" | "closed" | | `[data-invalid]` | Present when invalid | | `[data-focusable]` | | | `[data-readonly]` | Present when read-only | | `[data-disabled]` | Present when disabled | ### Context These are the properties available when using `Combobox.Context`, `useComboboxContext` hook or `useCombobox` hook. **API:** | Property | Type | Description | |----------|------|-------------| | `focused` | `boolean` | Whether the combobox is focused | | `open` | `boolean` | Whether the combobox is open | | `inputValue` | `string` | The value of the combobox input | | `highlightedValue` | `string` | The value of the highlighted item | | `highlightedItem` | `V` | The highlighted item | | `setHighlightValue` | `(value: string) => void` | The value of the combobox input | | `clearHighlightValue` | `VoidFunction` | Function to clear the highlighted value | | `syncSelectedItems` | `VoidFunction` | Function to sync the selected items with the value. Useful when `value` is updated from async sources. | | `selectedItems` | `V[]` | The selected items | | `hasSelectedItems` | `boolean` | Whether there's a selected item | | `value` | `string[]` | The selected item keys | | `valueAsString` | `string` | The string representation of the selected items | | `selectValue` | `(value: string) => void` | Function to select a value | | `setValue` | `(value: string[]) => void` | Function to set the value of the combobox | | `clearValue` | `(value?: string) => void` | Function to clear the value of the combobox | | `focus` | `VoidFunction` | Function to focus on the combobox input | | `setInputValue` | `(value: string, reason?: InputValueChangeReason) => void` | Function to set the input value of the combobox | | `getItemState` | `(props: ItemProps) => ItemState` | Returns the state of a combobox item | | `setOpen` | `(open: boolean, reason?: OpenChangeReason) => void` | Function to open or close the combobox | | `collection` | `ListCollection ` | Function to toggle the combobox | | `reposition` | `(options?: Partial ) => void` | Function to set the positioning options | | `multiple` | `boolean` | Whether the combobox allows multiple selections | | `disabled` | `boolean` | Whether the combobox is disabled | ## Accessibility Complies with the [Combobox WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/). ### Keyboard Support **`ArrowDown`** Description: When the combobox is closed, opens the listbox and highlights to the first option. When the combobox is open, moves focus to the next option. **`ArrowUp`** Description: When the combobox is closed, opens the listbox and highlights to the last option. When the combobox is open, moves focus to the previous option. **`Home`** Description: When the combobox is open, moves focus to the first option. **`End`** Description: When the combobox is open, moves focus to the last option. **`Escape`** Description: Closes the listbox. **`Enter`** Description: Selects the highlighted option and closes the combobox. **`Esc`** Description: Closes the combobox # Date Picker ## Anatomy To set up the date picker correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples Learn how to use the `DatePicker` component in your project. Let's take a look at the most basic example **Example: basic** #### React ```tsx import { DatePicker } from '@ark-ui/react/date-picker' import { Portal } from '@ark-ui/react/portal' export const Basic = () => { return ( Label 📅 Clear {(datePicker) => ( <> Prev Next {datePicker.weekDays.map((weekDay, id) => ( {weekDay.short} ))}{datePicker.weeks.map((week, id) => ( {week.map((day, id) => ( ))}{day.day} {(datePicker) => ( <> Prev Next {datePicker.getMonthsGrid({ columns: 4, format: 'short' }).map((months, id) => ( {months.map((month, id) => ( ))}{month.label} {(datePicker) => ( <> Prev Next {datePicker.getYearsGrid({ columns: 4 }).map((years, id) => ( {years.map((year, id) => ( ))}{year.label} Label 📅 Clear {(context) => ( <> Prev Next {(weekDay) => {weekDay().short} }{(week) => ( {(day) => ( {day().day} {(context) => ( <> Prev Next {(months) => ( {(month) => ( {month().label} {(context) => ( <> Prev Next {(years) => ( {(year) => ( {year().label} Label 📅 Clear Prev Next {{ weekDay.short }} {{ day.day }} Prev Next {{ month.label }} Prev Next {{ year.label }} Label 📅 Clear {#snippet render(datePicker)} Prev Next {#each datePicker().weekDays as weekDay} {weekDay.short} {/each}{#each datePicker().weeks as week} {#each week as day} {/each}{day.day} setValue(e.value)}> ) } ``` #### Solid ```tsx import { DatePicker, parseDate } from '@ark-ui/solid/date-picker' import { createSignal } from 'solid-js' import { Index, Portal } from 'solid-js/web' export const Controlled = () => { const [value, setValue] = createSignalLabel 📅 Clear {(datePicker) => ( <> Prev Next {datePicker.weekDays.map((weekDay, id) => ( {weekDay.short} ))}{datePicker.weeks.map((week, id) => ( {week.map((day, id) => ( ))}{day.day} {(datePicker) => ( <> Prev Next {datePicker.getMonthsGrid({ columns: 4, format: 'short' }).map((months, id) => ( {months.map((month, id) => ( ))}{month.label} {(datePicker) => ( <> Prev Next {datePicker.getYearsGrid({ columns: 4 }).map((years, id) => ( {years.map((year, id) => ( ))}{year.label} setValue(e.value)}> ) } ``` #### Vue ```vueLabel 📅 Clear {(context) => ( <> Prev Next {(weekDay) => {weekDay().short} }{(week) => ( {(day) => ( {day().day} {(context) => ( <> Prev Next {(months) => ( {(month) => ( {month().label} {(context) => ( <> Prev Next {(years) => ( {(year) => ( {year().label} Label 📅 Clear Prev Next {{ weekDay.short }} {{ day.day }} Prev Next {{ month.label }} Prev Next {{ year.label }} Label 📅 Clear {#snippet render(datePicker)} Prev Next {#each datePicker().weekDays as weekDay} {weekDay.short} {/each}{#each datePicker().weeks as week} {#each week as day} {/each}{day.day} Label 📅 Clear Last 7 days {(datePicker) => ( <> Prev Next {datePicker.weekDays.map((weekDay, id) => ( {weekDay.short} ))}{datePicker.weeks.map((week, id) => ( {week.map((day, id) => ( ))}{day.day} {(datePicker) => ( <> Prev Next {datePicker.getMonthsGrid({ columns: 4, format: 'short' }).map((months, id) => ( {months.map((month, id) => ( ))}{month.label} {(datePicker) => ( <> Prev Next {datePicker.getYearsGrid({ columns: 4 }).map((years, id) => ( {years.map((year, id) => ( ))}{year.label} Label 📅 Clear Last 7 days {(context) => ( {(weekDay) => {weekDay().short} }{(week) => ( {(day) => ( {day().day} {(context) => { const offset = createMemo(() => context().getOffset({ months: 1 })) return ( {(weekDay) => {weekDay().short} }{(week) => ( {(day) => ( {day().day} Label 📅 Clear Last 7 days Prev Next {{ weekDay.short }} {{ day.day }} Prev Next {{ month.label }} Prev Next {{ year.label }} Label 📅 Clear Last 7 days {#snippet render(datePicker)} Prev Next {#each datePicker().weekDays as weekDay} {weekDay.short} {/each}{#each datePicker().weeks as week} {#each week as day} {/each}{day.day} Label 📅 Clear Prev Next {/* First month */}{(datePicker) => ( {/* Second month */}{datePicker.weekDays.map((weekDay, id) => ( {weekDay.short} ))}{datePicker.weeks.map((week, id) => ( {week.map((day, id) => ( ))}{day.day} {(datePicker) => { const offset = datePicker.getOffset({ months: 1 }) return ( {datePicker.weekDays.map((weekDay, id) => ( {weekDay.short} ))}{offset.weeks.map((week, id) => ( {week.map((day, id) => ( ))}{day.day} Label 📅 Clear Prev Next {/* First month */}{(datePicker) => ( {/* Second month */}{(weekDay) => {weekDay().short} }{(week) => ( {(day) => ( {day().day} {(datePicker) => { const offset = createMemo(() => datePicker().getOffset({ months: 1 })) return ( {(weekDay) => {weekDay().short} }{(week) => ( {(day) => ( {day().day} Label 📅 Clear Prev Next {{ weekDay.short }} {{ day.day }} {{ weekDay.short }} {{ day.day }} Label 📅 Clear Prev Next {#snippet render(datePicker)} {#each datePicker().weekDays as weekDay, id (id)} {weekDay.short} {/each}{#each datePicker().weeks as week, id} {#each week as day, id (id)} {/each}{day.day} {#snippet render(datePicker)} {@const offset = datePicker().getOffset({ months: 1 })} {#each datePicker().weekDays as weekDay, id (id)} {weekDay.short} {/each}{#each offset.weeks as week, id (id)} {#each week as day, id (id)} {/each}{day.day} {(datePicker) => ( <> Prev Next {datePicker.weekDays.map((weekDay, id) => ( {weekDay.short} ))}{datePicker.weeks.map((week, id) => ( {week.map((day, id) => ( ))}{day.day} {(datePicker) => ( <> Prev Next {datePicker.getMonthsGrid({ columns: 4, format: 'short' }).map((months, id) => ( {months.map((month, id) => ( ))}{month.label} {(datePicker) => ( <> Prev Next {datePicker.getYearsGrid({ columns: 4 }).map((years, id) => ( {years.map((year, id) => ( ))}{year.label} {(context) => ( <> Prev Next {(weekDay) => {weekDay().short} }{(week) => ( {(day) => ( {day().day} {(context) => ( <> Prev Next {(months) => ( {(month) => ( {month().label} {(context) => ( <> Prev Next {(years) => ( {(year) => ( {year().label} Prev Next {{ weekDay.short }} {{ day.day }} Prev Next {{ month.label }} Prev Next {{ year.label }} {#snippet render(datePicker)} Prev Next {#each datePicker().weekDays as weekDay} {weekDay.short} {/each}{#each datePicker().weeks as week} {#each week as day} {/each}{day.day} {#snippet render(datePicker)} Prev Next {#each datePicker().getMonthsGrid({ columns: 4, format: 'short' }) as months} {#each months as month} {/each}{month.label} {#snippet render(datePicker)} Prev Next {#each datePicker().getYearsGrid({ columns: 4 }) as years} {#each years as year} {/each}{year.label} Label 📅 Clear {(datePicker) => ( <> Prev Next {datePicker.weekDays.map((weekDay, id) => ( {weekDay.short} ))}{datePicker.weeks.map((week, id) => ( {week.map((day, id) => ( ))}{day.day} {(datePicker) => ( <> Prev Next {datePicker.getMonthsGrid({ columns: 4, format: 'short' }).map((months, id) => ( {months.map((month, id) => ( ))}{month.label} {(datePicker) => ( <> Prev Next {datePicker.getYearsGrid({ columns: 4 }).map((years, id) => ( {years.map((year, id) => ( ))}{year.label} Label 📅 Clear {(context) => ( <> Prev Next {(weekDay) => {weekDay().short} }{(week) => ( {(day) => ( {day().day} {(context) => ( <> Prev Next {(months) => ( {(month) => ( {month().label} {(context) => ( <> Prev Next {(years) => ( {(year) => ( {year().label} Label 📅 Clear Prev Next {{ weekDay.short }} {{ day.day }} Prev Next {{ month.label }} Prev Next {{ year.label }} Label 📅 Clear Prev Next {#each datePicker().weekDays as weekDay} {weekDay.short} {/each}{#each datePicker().weeks as week} {#each week as day} {/each}{day.day} ` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **TableBody Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **TableBody Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | date-picker | | `[data-part]` | table-body | | `[data-view]` | The view of the tablebody | | `[data-disabled]` | Present when disabled | **TableCell Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `Reactive ` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `columns` | `number` | No | | | `disabled` | `boolean` | No | | | `visibleRange` | `VisibleRange` | No | | **TableCellTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **TableHead Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **TableHead Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | date-picker | | `[data-part]` | table-head | | `[data-view]` | The view of the tablehead | | `[data-disabled]` | Present when disabled | **TableHeader Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **TableHeader Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | date-picker | | `[data-part]` | table-header | | `[data-view]` | The view of the tableheader | | `[data-disabled]` | Present when disabled | **Table Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `columns` | `number` | No | | | `id` | `string` | No | | | `view` | `DateView` | No | | **Table Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | date-picker | | `[data-part]` | table | | `[data-columns]` | | | `[data-view]` | The view of the table | **TableRow Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **TableRow Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | date-picker | | `[data-part]` | table-row | | `[data-disabled]` | Present when disabled | | `[data-view]` | The view of the tablerow | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | date-picker | | `[data-part]` | trigger | | `[data-placement]` | The placement of the trigger | | `[data-state]` | "open" | "closed" | **ViewControl Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ViewControl Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | date-picker | | `[data-part]` | view-control | | `[data-view]` | The view of the viewcontrol | **View Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `view` | `DateView` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **View Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | date-picker | | `[data-part]` | view | | `[data-view]` | The view of the view | **ViewTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ViewTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | date-picker | | `[data-part]` | view-trigger | | `[data-view]` | The view of the viewtrigger | **YearSelect Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | #### Svelte **Root 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. | | `closeOnSelect` | `boolean` | No | Whether the calendar should close after the date selection is complete. This is ignored when the selection mode is `multiple`. | | `defaultFocusedValue` | `DateValue` | No | The initial focused date when rendered. Use when you don't need to control the focused date of the date picker. | | `defaultOpen` | `boolean` | No | The initial open state of the date picker when rendered. Use when you don't need to control the open state of the date picker. | | `defaultValue` | `DateValue[]` | No | The initial selected date(s) when rendered. Use when you don't need to control the selected date(s) of the date picker. | | `defaultView` | `DateView` | No | The default view of the calendar | | `disabled` | `boolean` | No | Whether the calendar is disabled. | | `fixedWeeks` | `boolean` | No | Whether the calendar should have a fixed number of weeks. This renders the calendar with 6 weeks instead of 5 or 6. | | `focusedValue` | `DateValue` | No | The controlled focused date. | | `format` | `(date: DateValue, details: LocaleDetails) => string` | No | The format of the date to display in the input. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string; label: (index: number) => string; table: (id: string) => string; tableHeader: (id: string) => string; tableBody: (id: string) => string; tableRow: (id: string) => string; content: string; ... 10 more ...; positioner: string; }>` | No | The ids of the elements in the date picker. Useful for composition. | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `inline` | `boolean` | No | Whether to render the date picker inline | | `isDateUnavailable` | `(date: DateValue, locale: string) => boolean` | No | Returns whether a date of the calendar is available. | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `locale` | `string` | No | The locale (BCP 47 language tag) to use when formatting the date. | | `max` | `DateValue` | No | The maximum date that can be selected. | | `maxView` | `DateView` | No | The maximum view of the calendar | | `min` | `DateValue` | No | The minimum date that can be selected. | | `minView` | `DateView` | No | The minimum view of the calendar | | `name` | `string` | No | The `name` attribute of the input element. | | `numOfMonths` | `number` | No | The number of months to display. | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `onFocusChange` | `(details: FocusChangeDetails) => void` | No | Function called when the focused date changes. | | `onOpenChange` | `(details: OpenChangeDetails) => void` | No | Function called when the calendar opens or closes. | | `onValueChange` | `(details: ValueChangeDetails) => void` | No | Function called when the value changes. | | `onViewChange` | `(details: ViewChangeDetails) => void` | No | Function called when the view changes. | | `open` | `boolean` | No | The controlled open state of the date picker | | `outsideDaySelectable` | `boolean` | No | Whether day outside the visible range can be selected. | | `parse` | `(value: string, details: LocaleDetails) => DateValue | undefined` | No | Function to parse the date from the input back to a DateValue. | | `placeholder` | `string` | No | The placeholder text to display in the input. | | `positioning` | `PositioningOptions` | No | The user provided options used to position the date picker content | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `readOnly` | `boolean` | No | Whether the calendar is read-only. | | `ref` | `Element` | No | | | `selectionMode` | `SelectionMode` | No | The selection mode of the calendar. - `single` - only one date can be selected - `multiple` - multiple dates can be selected - `range` - a range of dates can be selected | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `startOfWeek` | `number` | No | The first day of the week. `0` - Sunday `1` - Monday `2` - Tuesday `3` - Wednesday `4` - Thursday `5` - Friday `6` - Saturday | | `timeZone` | `string` | No | The time zone to use | | `translations` | `IntlTranslations` | No | The localized messages to use. | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | | `value` | `DateValue[]` | No | The controlled selected date(s). | | `view` | `DateView` | No | The view of the calendar | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | date-picker | | `[data-part]` | root | | `[data-state]` | "open" | "closed" | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | **ClearTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Content 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. | | `ref` | `Element` | No | | **Content Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | date-picker | | `[data-part]` | content | | `[data-state]` | "open" | "closed" | | `[data-nested]` | popover | | `[data-has-nested]` | popover | | `[data-placement]` | The placement of the content | | `[data-inline]` | Present when the content is inline | **Context Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `render` | `Snippet<[UseDatePickerContext]>` | Yes | | **Control 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. | | `ref` | `Element` | No | | **Control Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | date-picker | | `[data-part]` | control | | `[data-disabled]` | Present when disabled | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'input'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `fixOnBlur` | `boolean` | No | Whether to fix the input value on blur. | | `index` | `number` | No | The index of the input to focus. | | `ref` | `Element` | No | | **Input Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | date-picker | | `[data-part]` | input | | `[data-index]` | The index of the item | | `[data-state]` | "open" | "closed" | | `[data-invalid]` | Present when invalid | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'label'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | date-picker | | `[data-part]` | label | | `[data-state]` | "open" | "closed" | | `[data-index]` | The index of the item | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | **MonthSelect Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'select'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **NextTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **NextTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | date-picker | | `[data-part]` | next-trigger | | `[data-disabled]` | Present when disabled | **Positioner 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. | | `ref` | `Element` | No | | **PresetTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `PresetTriggerValue` | Yes | | | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **PrevTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **PrevTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | date-picker | | `[data-part]` | prev-trigger | | `[data-disabled]` | Present when disabled | **RangeText 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. | | `ref` | `Element` | No | | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseDatePickerReturn` | Yes | | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **TableBody Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'tbody'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **TableBody Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | date-picker | | `[data-part]` | table-body | | `[data-view]` | The view of the tablebody | | `[data-disabled]` | Present when disabled | **TableCell Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `number | DateValue` | Yes | | | `asChild` | `Snippet<[PropsFn<'td'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `columns` | `number` | No | | | `disabled` | `boolean` | No | | | `ref` | `Element` | No | | | `visibleRange` | `VisibleRange` | No | | **TableCellTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **TableHead Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'thead'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **TableHead Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | date-picker | | `[data-part]` | table-head | | `[data-view]` | The view of the tablehead | | `[data-disabled]` | Present when disabled | **TableHeader Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'th'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **TableHeader Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | date-picker | | `[data-part]` | table-header | | `[data-view]` | The view of the tableheader | | `[data-disabled]` | Present when disabled | **Table Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'table'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `columns` | `number` | No | | **Table Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | date-picker | | `[data-part]` | table | | `[data-columns]` | | | `[data-view]` | The view of the table | **TableRow Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'tr'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **TableRow Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | date-picker | | `[data-part]` | table-row | | `[data-disabled]` | Present when disabled | | `[data-view]` | The view of the tablerow | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | date-picker | | `[data-part]` | trigger | | `[data-placement]` | The placement of the trigger | | `[data-state]` | "open" | "closed" | **ViewControl 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. | | `ref` | `Element` | No | | **ViewControl Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | date-picker | | `[data-part]` | view-control | | `[data-view]` | The view of the viewcontrol | **View 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. | | `ref` | `Element` | No | | | `view` | `DateView` | No | | **View Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | date-picker | | `[data-part]` | view | | `[data-view]` | The view of the view | **ViewTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **ViewTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | date-picker | | `[data-part]` | view-trigger | | `[data-view]` | The view of the viewtrigger | **YearSelect Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'select'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | ### Context These are the properties available when using `UdateUpicker.Context`, `useUdateUpickerContext` hook or `useUdateUpicker` hook. **API:** | Property | Type | Description | |----------|------|-------------| | `focused` | `boolean` | Whether the input is focused | | `open` | `boolean` | Whether the date picker is open | | `disabled` | `boolean` | Whether the date picker is disabled | | `invalid` | `boolean` | Whether the date picker is invalid | | `inline` | `boolean` | Whether the date picker is rendered inline | | `view` | `DateView` | The current view of the date picker | | `getDaysInWeek` | `(week: number, from?: DateValue) => DateValue[]` | Returns an array of days in the week index counted from the provided start date, or the first visible date if not given. | | `getOffset` | `(duration: DateDuration) => DateValueOffset` | Returns the offset of the month based on the provided number of months. | | `getRangePresetValue` | `(value: DateRangePreset) => DateValue[]` | Returns the range of dates based on the provided date range preset. | | `getMonthWeeks` | `(from?: DateValue) => DateValue[][]` | Returns the weeks of the month from the provided date. Represented as an array of arrays of dates. | | `isUnavailable` | `(date: DateValue) => boolean` | Returns whether the provided date is available (or can be selected) | | `weeks` | `DateValue[][]` | The weeks of the month. Represented as an array of arrays of dates. | | `weekDays` | `WeekDay[]` | The days of the week. Represented as an array of strings. | | `visibleRange` | `VisibleRange` | The visible range of dates. | | `visibleRangeText` | `VisibleRangeText` | The human readable text for the visible range of dates. | | `value` | `DateValue[]` | The selected date. | | `valueAsDate` | `Date[]` | The selected date as a Date object. | | `valueAsString` | `string[]` | The selected date as a string. | | `focusedValue` | `DateValue` | The focused date. | | `focusedValueAsDate` | `Date` | The focused date as a Date object. | | `focusedValueAsString` | `string` | The focused date as a string. | | `selectToday` | `VoidFunction` | Sets the selected date to today. | | `setValue` | `(values: DateValue[]) => void` | Sets the selected date to the given date. | | `setFocusedValue` | `(value: DateValue) => void` | Sets the focused date to the given date. | | `clearValue` | `VoidFunction` | Clears the selected date(s). | | `setOpen` | `(open: boolean) => void` | Function to open or close the calendar. | | `focusMonth` | `(month: number) => void` | Function to set the selected month. | | `focusYear` | `(year: number) => void` | Function to set the selected year. | | `getYears` | `() => Cell[]` | Returns the months of the year | | `getYearsGrid` | `(props?: YearGridProps) => YearGridValue` | Returns the years of the decade based on the columns. Represented as an array of arrays of years. | | `getDecade` | `() => Range ` | Returns the start and end years of the decade. | | `getMonths` | `(props?: MonthFormatOptions) => Cell[]` | Returns the months of the year | | `getMonthsGrid` | `(props?: MonthGridProps) => MonthGridValue` | Returns the months of the year based on the columns. Represented as an array of arrays of months. | | `format` | `(value: DateValue, opts?: Intl.DateTimeFormatOptions) => string` | Formats the given date value based on the provided options. | | `setView` | `(view: DateView) => void` | Sets the view of the date picker. | | `goToNext` | `VoidFunction` | Goes to the next month/year/decade. | | `goToPrev` | `VoidFunction` | Goes to the previous month/year/decade. | | `getDayTableCellState` | `(props: DayTableCellProps) => DayTableCellState` | Returns the state details for a given cell. | | `getMonthTableCellState` | `(props: TableCellProps) => TableCellState` | Returns the state details for a given month cell. | | `getYearTableCellState` | `(props: TableCellProps) => TableCellState` | Returns the state details for a given year cell. | ## Accessibility ### Keyboard Support **`ArrowLeft`** Description: Moves focus to the previous day within the current week. **`ArrowRight`** Description: Moves focus to the next day within the current week. **`ArrowUp`** Description: Moves focus to the same day of the week in the previous week. **`ArrowDown`** Description: Moves focus to the same day of the week in the next week. **`Home`** Description: Moves focus to the first day of the current month. **`End`** Description: Moves focus to the last day of the current month. **`PageUp`** Description: Moves focus to the same day of the month in the previous month. **`PageDown`** Description: Moves focus to the same day of the month in the next month. **`Enter`** Description: Selects the focused date and closes the date picker. **`Esc`** Description: Closes the date picker without selecting any date. # Dialog ## Anatomy To use the dialog component correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples Learn how to use the `Dialog` component in your project. Let's take a look at the most basic example **Example: basic** #### React ```tsx import { Dialog } from '@ark-ui/react/dialog' import { Portal } from '@ark-ui/react/portal' import { XIcon } from 'lucide-react' export const Basic = () => ( Open Dialog Dialog Title Dialog Description Open Dialog Dialog Title Dialog Description Open Dialog Dialog Title Dialog Description Open Dialog Dialog Title Dialog Description setIsOpen(e.open)}> ) } ``` #### Solid ```tsx import { XIcon } from 'lucide-solid' import { Dialog } from '@ark-ui/solid/dialog' import { createSignal } from 'solid-js' import { Portal } from 'solid-js/web' export const Controlled = () => { const [open, setOpen] = createSignal(false) return ( <>Dialog Title Dialog Description setOpen(false)}> ) } ``` #### Vue ```vueDialog Title Dialog Description Dialog Title Dialog Description Controlled Dialog This dialog's open state is controlled externally. console.log('onExitComplete invoked')}> ) ``` #### Solid ```tsx import { XIcon } from 'lucide-solid' import { Dialog } from '@ark-ui/solid/dialog' export const LazyMount = () => { return (Open Dialog Dialog Title Dialog Description Open Dialog Dialog Title Dialog Description Open Dialog Dialog Title Dialog Description console.log('onExitComplete invoked')}> ``` ### Alert Dialog For critical confirmations or destructive actions, use `role="alertdialog"`. Alert dialogs differ from regular dialogs in important ways: - **Automatic focus**: The close/cancel button receives focus when opened, prioritizing the safest action - **Requires explicit dismissal**: Cannot be closed by clicking outside, only via button clicks or Escape key **Example: alert-dialog** #### React ```tsx import { Dialog } from '@ark-ui/react/dialog' import { Portal } from '@ark-ui/react/portal' import { XIcon } from 'lucide-react' export const AlertDialog = () => (Open Dialog Lazy Mounted Dialog This dialog content is only rendered when the dialog is first opened. Delete Account Are you absolutely sure? This action cannot be undone. This will permanently delete your account and remove your data from our servers. Delete Account Are you absolutely sure? This action cannot be undone. This will permanently delete your account and remove your data from our servers. Delete Account Are you absolutely sure? This action cannot be undone. This will permanently delete your account and remove your data from our servers. Cancel Delete Account Are you absolutely sure? This action cannot be undone. This will permanently delete your account and remove your data from our servers. Cancel (null) return ( inputRef.current}> ) } ``` #### Solid ```tsx import { XIcon } from 'lucide-solid' import { Dialog } from '@ark-ui/solid/dialog' import { Portal } from 'solid-js/web' export const InitialFocus = () => { let inputRef: HTMLInputElement | null = null return (Open Dialog Edit Profile Make changes to your profile here. The first input will be focused when the dialog opens. inputRef}> ) } ``` #### Vue ```vueOpen Dialog Edit Profile Make changes to your profile here. The first input will be focused when the dialog opens. Open Dialog Edit Profile Make changes to your profile here. The first input will be focused when the dialog opens. inputRef}> ``` ### Final Focus Control which element receives focus when the dialog closes using the `finalFocusEl` prop. By default, focus returns to the trigger element, but you can specify a different element: **Example: final-focus** #### React ```tsx import { Dialog } from '@ark-ui/react/dialog' import { Portal } from '@ark-ui/react/portal' import { XIcon } from 'lucide-react' import { useRef } from 'react' export const FinalFocus = () => { const finalRef = useRefOpen Dialog Edit Profile Make changes to your profile here. The first input will be focused when the dialog opens. (null) return ( <> finalRef.current}> ) } ``` #### Solid ```tsx import { XIcon } from 'lucide-solid' import { Dialog } from '@ark-ui/solid/dialog' import { Portal } from 'solid-js/web' export const FinalFocus = () => { let finalRef: HTMLButtonElement | null = null return ( <>Open Dialog Dialog Title When this dialog closes, focus will return to the button above instead of the trigger. finalRef}> ) } ``` #### Vue ```vueOpen Dialog Dialog Title When this dialog closes, focus will return to the button above instead of the trigger. Open Dialog Dialog Title When this dialog closes, focus will return to the button above instead of the trigger. finalRef}> ``` ### Non-Modal Dialog Use `modal={false}` to create a non-modal dialog that allows interaction with elements outside of it. This disables focus trapping, scroll prevention, and pointer blocking, making it useful for auxiliary panels or inspector windows: **Example: non-modal** #### React ```tsx import { Dialog } from '@ark-ui/react/dialog' import { Portal } from '@ark-ui/react/portal' import { XIcon } from 'lucide-react' export const NonModal = () => (Open Dialog Dialog Title When this dialog closes, focus will return to the button above instead of the trigger. Open Non-Modal Dialog Non-Modal Dialog This dialog allows interaction with elements outside. You can click buttons, select text, and interact with the page behind it. Open Non-Modal Dialog Non-Modal Dialog This dialog allows interaction with elements outside. You can click buttons, select text, and interact with the page behind it. Open Non-Modal Dialog Non-Modal Dialog This dialog allows interaction with elements outside. You can click buttons, select text, and interact with the page behind it. Open Non-Modal Dialog Non-Modal Dialog This dialog allows interaction with elements outside. You can click buttons, select text, and interact with the page behind it. { const target = e.target as HTMLElement if (target.closest('[data-allow-close]')) { return } e.preventDefault() }} > ) ``` #### Solid ```tsx import { XIcon } from 'lucide-solid' import { Dialog } from '@ark-ui/solid/dialog' import { Portal } from 'solid-js/web' export const CloseOnInteractOutside = () => { return (Open Dialog Custom Close Behavior This dialog will not close when clicking outside. Try clicking the backdrop or pressing Escape to see that it stays open. Only the close button will dismiss it. { const target = e.target as HTMLElement if (target.closest('[data-allow-close]')) { return } e.preventDefault() }} > ) } ``` #### Vue ```vueOpen Dialog Custom Close Behavior This dialog will not close when clicking outside. Try clicking the backdrop or pressing Escape to see that it stays open. Only the close button will dismiss it. Open Dialog Custom Close Behavior This dialog will not close when clicking outside. Try clicking the backdrop or pressing Escape to see that it stays open. Only the close button will dismiss it. Open Dialog Custom Close Behavior This dialog will not close when clicking outside. Try clicking the backdrop or pressing Escape to see that it stays open. Only the close button will dismiss it. { const hasUnsavedChanges = true if (hasUnsavedChanges) { e.preventDefault() alert('You have unsaved changes. Please save or discard them before closing.') } }} > ) ``` #### Solid ```tsx import { XIcon } from 'lucide-solid' import { Dialog } from '@ark-ui/solid/dialog' import { Portal } from 'solid-js/web' export const CloseOnEscape = () => { return (Open Dialog Unsaved Changes This dialog prevents closing with Escape key. Try pressing Escape to see the warning. Use the close button to dismiss. { const hasUnsavedChanges = true if (hasUnsavedChanges) { e.preventDefault() alert('You have unsaved changes. Please save or discard them before closing.') } }} > ) } ``` #### Vue ```vueOpen Dialog Unsaved Changes This dialog prevents closing with Escape key. Try pressing Escape to see the warning. Use the close button to dismiss. Open Dialog Unsaved Changes This dialog prevents closing with Escape key. Try pressing Escape to see the warning. Use the close button to dismiss. Open Dialog Unsaved Changes This dialog prevents closing with Escape key. Try pressing Escape to see the warning. Use the close button to dismiss. Open Dialog Dialog Title Dialog Description {(dialog) => Dialog is {dialog.open ? 'open' : 'closed'}
}Open Dialog Dialog Title Dialog Description {(context) => Dialog is {context().open ? 'open' : 'closed'}
}Open Dialog Dialog Title Dialog Description Dialog is {{ dialog.open ? 'open' : 'closed' }}
{#snippet children(dialog)} {dialog().open ? 'Close' : 'Open'} Dialog Dialog State: {dialog().open ? 'Open' : 'Closed'} This example uses a render function to access dialog state. Open Dialog Dialog Title Dialog Description Open Dialog Dialog Title Dialog Description Open Dialog Dialog Title Dialog Description Open Dialog Dialog Title Dialog Description Parent Dialog This is the parent dialog. Open a nested dialog from here to see automatic z-index management via CSS variables like --z-index and --layer-index. Nested Dialog This dialog is nested within the parent. Notice how it layers on top with proper z-index management. Parent Dialog This is the parent dialog. Open a nested dialog from here to see automatic z-index management via CSS variables like --z-index and --layer-index. Nested Dialog This dialog is nested within the parent. Notice how it layers on top with proper z-index management. Parent Dialog This is the parent dialog. Open a nested dialog from here to see automatic z-index management via CSS variables like --z-index and --layer-index. Nested Dialog This dialog is nested within the parent. Notice how it layers on top with proper z-index management. Parent Dialog This is the parent dialog. Open a nested dialog from here to see automatic z-index management via CSS variables like `--z-index` and `--layer-index`. Nested Dialog This dialog is nested within the parent. Notice how it layers on top with proper z-index management. Edit Content Make changes to your content. If you have unsaved changes, you'll be asked to confirm before closing. Unsaved Changes You have unsaved changes. Are you sure you want to close without saving? Open Dialog Loading...}> ` | Yes | | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Title Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | dialog | | `[data-part]` | trigger | | `[data-state]` | "open" | "closed" | #### Svelte **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `aria-label` | `string` | No | Human readable label for the dialog, in event the dialog title is not rendered | | `closeOnEscape` | `boolean` | No | Whether to close the dialog when the escape key is pressed | | `closeOnInteractOutside` | `boolean` | No | Whether to close the dialog when the outside is clicked | | `defaultOpen` | `boolean` | No | The initial open state of the dialog when rendered. Use when you don't need to control the open state of the dialog. | | `finalFocusEl` | `() => MaybeElement` | No | Element to receive focus when the dialog is closed | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ trigger: string positioner: string backdrop: string content: string closeTrigger: string title: string description: string }>` | No | The ids of the elements in the dialog. Useful for composition. | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `initialFocusEl` | `() => MaybeElement` | No | Element to receive focus when the dialog is opened | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `modal` | `boolean` | No | Whether to prevent pointer interaction outside the element and hide all content below it | | `onEscapeKeyDown` | `(event: KeyboardEvent) => void` | No | Function called when the escape key is pressed | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component | | `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component | | `onOpenChange` | `(details: OpenChangeDetails) => void` | No | Function to call when the dialog's open state changes | | `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component | | `onRequestDismiss` | `(event: LayerDismissEvent) => void` | No | Function called when this layer is closed due to a parent layer being closed | | `open` | `boolean` | No | The controlled open state of the dialog | | `persistentElements` | `(() => Element | null)[]` | No | Returns the persistent elements that: - should not have pointer-events disabled - should not trigger the dismiss event | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `preventScroll` | `boolean` | No | Whether to prevent scrolling behind the dialog when it's opened | | `restoreFocus` | `boolean` | No | Whether to restore focus to the element that had focus before the dialog was opened | | `role` | `'alertdialog' | 'dialog'` | No | The dialog's role | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `trapFocus` | `boolean` | No | Whether to trap focus inside the dialog when it's opened | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Backdrop 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. | | `ref` | `Element` | No | | **Backdrop Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | dialog | | `[data-part]` | backdrop | | `[data-state]` | "open" | "closed" | **CloseTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Content 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. | | `ref` | `Element` | No | | **Content Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | dialog | | `[data-part]` | content | | `[data-state]` | "open" | "closed" | | `[data-nested]` | dialog | | `[data-has-nested]` | dialog | **Description Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'p'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Positioner 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. | | `ref` | `Element` | No | | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseDialogReturn` | Yes | | **Title Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'h2'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | dialog | | `[data-part]` | trigger | | `[data-state]` | "open" | "closed" | ### Context These are the properties available when using `Dialog.Context`, `useDialogContext` hook or `useDialog` hook. **API:** | Property | Type | Description | |----------|------|-------------| | `open` | `boolean` | Whether the dialog is open | | `setOpen` | `(open: boolean) => void` | Function to open or close the dialog | ## Accessibility Complies with the [Dialog WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/). ### Keyboard Support **`Enter`** Description: When focus is on the trigger, opens the dialog. **`Tab`** Description: Moves focus to the next focusable element within the content. Focus is trapped within the dialog. **`Shift + Tab`** Description: Moves focus to the previous focusable element. Focus is trapped within the dialog. **`Esc`** Description: Closes the dialog and moves focus to trigger or the defined final focus element # Editable ## Anatomy To set up the editable correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples Learn how to use the `Editable` component in your project. Let's take a look at the most basic example: **Example: basic** #### React ```tsx import { Editable } from '@ark-ui/react/editable' export const Basic = () => ( Label Label Label Label Label {(editable) => ( {editable.editing ? ( <> )}Save Cancel ) : (Edit )}Label {(editable) => ( Edit}> Save Canvel Label Save Cancel Edit Label {#snippet render(editable)} {#if editable().editing} {/snippet}Save Cancel {:else}Edit {/if}Label Additional Info Error Info Label Additional Info Error Info Label Additional Info Error Info Label Additional Info Error Info Label Label Label Label {/*...*/} ``` ### Max Length Use the `maxLength` prop to set a maximum number of characters that can be entered into the editable. ```tsx{/*...*/} ``` ### Double click activation The editable supports two modes of activating the "edit" state: - when the preview part is focused (with pointer or keyboard). - when the preview part is double-clicked. To change the mode to double-click, pass the prop `activationMode="dblclick"`. ```tsx{/*...*/} ``` ## API Reference ### Props **Component API Reference** #### React **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `activationMode` | `ActivationMode` | No | The activation mode for the preview element. - "focus" - Enter edit mode when the preview is focused - "dblclick" - Enter edit mode when the preview is double-clicked - "click" - Enter edit mode when the preview is clicked - "none" - Edit can be triggered programmatically only | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `autoResize` | `boolean` | No | Whether the editable should auto-resize to fit the content. | | `defaultEdit` | `boolean` | No | Whether the editable is in edit mode by default. | | `defaultValue` | `string` | No | The initial value of the editable when rendered. Use when you don't need to control the value of the editable. | | `disabled` | `boolean` | No | Whether the editable is disabled. | | `edit` | `boolean` | No | Whether the editable is in edit mode. | | `finalFocusEl` | `() => HTMLElement | null` | No | The element to receive focus when the editable is closed. | | `form` | `string` | No | The associate form of the underlying input. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string area: string label: string preview: string input: string control: string submitTrigger: string cancelTrigger: string editTrigger: string }>` | No | The ids of the elements in the editable. Useful for composition. | | `invalid` | `boolean` | No | Whether the input's value is invalid. | | `maxLength` | `number` | No | The maximum number of characters allowed in the editable | | `name` | `string` | No | The name attribute of the editable component. Used for form submission. | | `onEditChange` | `(details: EditChangeDetails) => void` | No | Function to call when the edit mode changes. | | `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component | | `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component | | `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component | | `onValueChange` | `(details: ValueChangeDetails) => void` | No | Function to call when the value changes. | | `onValueCommit` | `(details: ValueChangeDetails) => void` | No | Function to call when the value is committed. | | `onValueRevert` | `(details: ValueChangeDetails) => void` | No | Function to call when the value is reverted. | | `placeholder` | `string | { edit: string; preview: string }` | No | The placeholder text for the editable. | | `readOnly` | `boolean` | No | Whether the editable is read-only. | | `required` | `boolean` | No | Whether the editable is required. | | `selectOnFocus` | `boolean` | No | Whether to select the text in the input when it is focused. | | `submitMode` | `SubmitMode` | No | The action that triggers submit in the edit mode: - "enter" - Trigger submit when the enter key is pressed - "blur" - Trigger submit when the editable is blurred - "none" - No action will trigger submit. You need to use the submit button - "both" - Pressing `Enter` and blurring the input will trigger submit | | `translations` | `IntlTranslations` | No | The translations for the editable. | | `value` | `string` | No | The controlled value of the editable. | **Area Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Area Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | editable | | `[data-part]` | area | | `[data-focus]` | Present when focused | | `[data-disabled]` | Present when disabled | | `[data-placeholder-shown]` | Present when placeholder is shown | **CancelTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Control Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **EditTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | editable | | `[data-part]` | input | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | | `[data-invalid]` | Present when invalid | | `[data-autoresize]` | | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | editable | | `[data-part]` | label | | `[data-focus]` | Present when focused | | `[data-invalid]` | Present when invalid | | `[data-required]` | Present when required | **Preview Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Preview Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | editable | | `[data-part]` | preview | | `[data-placeholder-shown]` | Present when placeholder is shown | | `[data-readonly]` | Present when read-only | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-autoresize]` | | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseEditableReturn` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **SubmitTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | #### Solid **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `activationMode` | `ActivationMode` | No | The activation mode for the preview element. - "focus" - Enter edit mode when the preview is focused - "dblclick" - Enter edit mode when the preview is double-clicked - "click" - Enter edit mode when the preview is clicked - "none" - Edit can be triggered programmatically only | | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `autoResize` | `boolean` | No | Whether the editable should auto-resize to fit the content. | | `defaultEdit` | `boolean` | No | Whether the editable is in edit mode by default. | | `defaultValue` | `string` | No | The initial value of the editable when rendered. Use when you don't need to control the value of the editable. | | `disabled` | `boolean` | No | Whether the editable is disabled. | | `edit` | `boolean` | No | Whether the editable is in edit mode. | | `finalFocusEl` | `() => HTMLElement | null` | No | The element to receive focus when the editable is closed. | | `form` | `string` | No | The associate form of the underlying input. | | `ids` | `Partial<{ root: string area: string label: string preview: string input: string control: string submitTrigger: string cancelTrigger: string editTrigger: string }>` | No | The ids of the elements in the editable. Useful for composition. | | `invalid` | `boolean` | No | Whether the input's value is invalid. | | `maxLength` | `number` | No | The maximum number of characters allowed in the editable | | `name` | `string` | No | The name attribute of the editable component. Used for form submission. | | `onEditChange` | `(details: EditChangeDetails) => void` | No | Function to call when the edit mode changes. | | `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component | | `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component | | `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component | | `onValueChange` | `(details: ValueChangeDetails) => void` | No | Function to call when the value changes. | | `onValueCommit` | `(details: ValueChangeDetails) => void` | No | Function to call when the value is committed. | | `onValueRevert` | `(details: ValueChangeDetails) => void` | No | Function to call when the value is reverted. | | `placeholder` | `string | { edit: string; preview: string }` | No | The placeholder text for the editable. | | `readOnly` | `boolean` | No | Whether the editable is read-only. | | `required` | `boolean` | No | Whether the editable is required. | | `selectOnFocus` | `boolean` | No | Whether to select the text in the input when it is focused. | | `submitMode` | `SubmitMode` | No | The action that triggers submit in the edit mode: - "enter" - Trigger submit when the enter key is pressed - "blur" - Trigger submit when the editable is blurred - "none" - No action will trigger submit. You need to use the submit button - "both" - Pressing `Enter` and blurring the input will trigger submit | | `translations` | `IntlTranslations` | No | The translations for the editable. | | `value` | `string` | No | The controlled value of the editable. | **Area 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. | **Area Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | editable | | `[data-part]` | area | | `[data-focus]` | Present when focused | | `[data-disabled]` | Present when disabled | | `[data-placeholder-shown]` | Present when placeholder is shown | **CancelTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Control 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. | **EditTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'input'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | editable | | `[data-part]` | input | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | | `[data-invalid]` | Present when invalid | | `[data-autoresize]` | | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'label'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | editable | | `[data-part]` | label | | `[data-focus]` | Present when focused | | `[data-invalid]` | Present when invalid | | `[data-required]` | Present when required | **Preview Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'span'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Preview Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | editable | | `[data-part]` | preview | | `[data-placeholder-shown]` | Present when placeholder is shown | | `[data-readonly]` | Present when read-only | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-autoresize]` | | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseEditableReturn` | Yes | | | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **SubmitTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | #### Vue **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `activationMode` | `ActivationMode` | No | The activation mode for the preview element. - "focus" - Enter edit mode when the preview is focused - "dblclick" - Enter edit mode when the preview is double-clicked - "click" - Enter edit mode when the preview is clicked | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `autoResize` | `boolean` | No | Whether the editable should auto-resize to fit the content. | | `defaultEdit` | `boolean` | No | Whether the editable is in edit mode by default. | | `defaultValue` | `string` | No | The initial value of the editable when rendered. Use when you don't need to control the value of the editable. | | `disabled` | `boolean` | No | Whether the editable is disabled. | | `edit` | `boolean` | No | Whether the editable is in edit mode. | | `finalFocusEl` | `() => HTMLElement | null` | No | The element to receive focus when the editable is closed. | | `form` | `string` | No | The associate form of the underlying input. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string area: string label: string preview: string input: string control: string submitTrigger: string cancelTrigger: string editTrigger: string }>` | No | The ids of the elements in the editable. Useful for composition. | | `invalid` | `boolean` | No | Whether the input's value is invalid. | | `maxLength` | `number` | No | The maximum number of characters allowed in the editable | | `modelValue` | `string` | No | The v-model value of the editable | | `name` | `string` | No | The name attribute of the editable component. Used for form submission. | | `placeholder` | `string | { edit: string; preview: string }` | No | The placeholder text for the editable. | | `readOnly` | `boolean` | No | Whether the editable is read-only. | | `required` | `boolean` | No | Whether the editable is required. | | `selectOnFocus` | `boolean` | No | Whether to select the text in the input when it is focused. | | `submitMode` | `SubmitMode` | No | The action that triggers submit in the edit mode: - "enter" - Trigger submit when the enter key is pressed - "blur" - Trigger submit when the editable is blurred - "none" - No action will trigger submit. You need to use the submit button - "both" - Pressing `Enter` and blurring the input will trigger submit | | `translations` | `IntlTranslations` | No | The translations for the editable. | **Area Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Area Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | editable | | `[data-part]` | area | | `[data-focus]` | Present when focused | | `[data-disabled]` | Present when disabled | | `[data-placeholder-shown]` | Present when placeholder is shown | **CancelTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Control Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **EditTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | editable | | `[data-part]` | input | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | | `[data-invalid]` | Present when invalid | | `[data-autoresize]` | | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | editable | | `[data-part]` | label | | `[data-focus]` | Present when focused | | `[data-invalid]` | Present when invalid | | `[data-required]` | Present when required | **Preview Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Preview Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | editable | | `[data-part]` | preview | | `[data-placeholder-shown]` | Present when placeholder is shown | | `[data-readonly]` | Present when read-only | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-autoresize]` | | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `EditableApi` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **SubmitTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | #### Svelte **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `activationMode` | `ActivationMode` | No | The activation mode for the preview element. - "focus" - Enter edit mode when the preview is focused - "dblclick" - Enter edit mode when the preview is double-clicked - "click" - Enter edit mode when the preview is clicked - "none" - Edit can be triggered programmatically only | | `autoResize` | `boolean` | No | Whether the editable should auto-resize to fit the content. | | `defaultEdit` | `boolean` | No | Whether the editable is in edit mode by default. | | `defaultValue` | `string` | No | The initial value of the editable when rendered. Use when you don't need to control the value of the editable. | | `disabled` | `boolean` | No | Whether the editable is disabled. | | `edit` | `boolean` | No | Whether the editable is in edit mode. | | `finalFocusEl` | `() => HTMLElement | null` | No | The element to receive focus when the editable is closed. | | `form` | `string` | No | The associate form of the underlying input. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string area: string label: string preview: string input: string control: string submitTrigger: string cancelTrigger: string editTrigger: string }>` | No | The ids of the elements in the editable. Useful for composition. | | `invalid` | `boolean` | No | Whether the input's value is invalid. | | `maxLength` | `number` | No | The maximum number of characters allowed in the editable | | `name` | `string` | No | The name attribute of the editable component. Used for form submission. | | `onEditChange` | `(details: EditChangeDetails) => void` | No | Function to call when the edit mode changes. | | `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component | | `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component | | `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component | | `onValueChange` | `(details: ValueChangeDetails) => void` | No | Function to call when the value changes. | | `onValueCommit` | `(details: ValueChangeDetails) => void` | No | Function to call when the value is committed. | | `onValueRevert` | `(details: ValueChangeDetails) => void` | No | Function to call when the value is reverted. | | `placeholder` | `string | { edit: string; preview: string }` | No | The placeholder text for the editable. | | `readOnly` | `boolean` | No | Whether the editable is read-only. | | `ref` | `Element` | No | | | `required` | `boolean` | No | Whether the editable is required. | | `selectOnFocus` | `boolean` | No | Whether to select the text in the input when it is focused. | | `submitMode` | `SubmitMode` | No | The action that triggers submit in the edit mode: - "enter" - Trigger submit when the enter key is pressed - "blur" - Trigger submit when the editable is blurred - "none" - No action will trigger submit. You need to use the submit button - "both" - Pressing `Enter` and blurring the input will trigger submit | | `translations` | `IntlTranslations` | No | The translations for the editable. | | `value` | `string` | No | The controlled value of the editable. | **Area 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. | | `ref` | `Element` | No | | **Area Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | editable | | `[data-part]` | area | | `[data-focus]` | Present when focused | | `[data-disabled]` | Present when disabled | | `[data-placeholder-shown]` | Present when placeholder is shown | **CancelTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Context Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `render` | `Snippet<[UseEditableContext]>` | Yes | | **Control 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. | | `ref` | `Element` | No | | **EditTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'input'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Input Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | editable | | `[data-part]` | input | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | | `[data-invalid]` | Present when invalid | | `[data-autoresize]` | | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'label'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | editable | | `[data-part]` | label | | `[data-focus]` | Present when focused | | `[data-invalid]` | Present when invalid | | `[data-required]` | Present when required | **Preview Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Preview Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | editable | | `[data-part]` | preview | | `[data-placeholder-shown]` | Present when placeholder is shown | | `[data-readonly]` | Present when read-only | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-autoresize]` | | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseEditableReturn` | Yes | | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **SubmitTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | ### Context These are the properties available when using `Editable.Context`, `useEditableContext` hook or `useEditable` hook. **API:** | Property | Type | Description | |----------|------|-------------| | `editing` | `boolean` | Whether the editable is in edit mode | | `empty` | `boolean` | Whether the editable value is empty | | `value` | `string` | The current value of the editable | | `valueText` | `string` | The current value of the editable, or the placeholder if the value is empty | | `setValue` | `(value: string) => void` | Function to set the value of the editable | | `clearValue` | `VoidFunction` | Function to clear the value of the editable | | `edit` | `VoidFunction` | Function to enter edit mode | | `cancel` | `VoidFunction` | Function to exit edit mode, and discard any changes | | `submit` | `VoidFunction` | Function to exit edit mode, and submit any changes | ## Accessibility ### Keyboard Support **`Enter`** Description: Saves the edited content and exits edit mode. **`Escape`** Description: Discards the changes and exits edit mode. # Field ## Examples The `Field` component provides contexts such as `invalid`, `disabled`, `required`, and `readOnly` for form elements. While most Ark UI components natively support these contexts, you can also use the `Field` component with standard HTML form elements. ### Input This example shows how to use the `Field` component with a standard input field. **Example: input** #### React ```tsx import { Field } from '@ark-ui/react/field' export const Input = () => { return ( Label Some additional Info Error Info Label Some additional Info Error Info Label Some additional Info Error Info Label Some additional Info Error Info Label Some additional Info Error Info Label Some additional Info Error Info Label Some additional Info Error Info Message Please provide as much detail as possible Label Some additional Info Error Info Label Some additional Info Error Info Label Some additional Info Error Info Message Please provide as much detail as possible Label Some additional Info Error Info Label Some additional Info Error Info Label Some additional Info Error Info Country Please select your country of residence Label Additional Info Error Info Label Some additional Info Error Info Label Some additional Info Error Info Label Some additional Info Error Info Label * This field has an error {#snippet render(field)} ``` > If you're using the `Field.RootProvider` component, you don't need to use the `Field.Root` component. ### Custom Control Use the `Field.Context` or `useFieldContext` hook to access the internal state of the field.This can help you wire up custom controls with the `Field` component. **Example: custom-control** #### React ```tsx import { Field } from '@ark-ui/react/field' export const CustomControl = () => { return (Field ID: {field().ids.control}
Required: {field().required}
Invalid: {field().invalid}
{/snippet}Any Control {(field) => } Uses getControlProps() for maximum flexibility This field has an error Any Control {(field) => } Uses getControlProps() for maximum flexibility This field has an error Any Control Uses getControlProps() for maximum flexibility This field has an error Any Control {#snippet render(field)} {/snippet} Uses getControlProps() for maximum flexibility This field has an error | ReactPortal | Promise<...>` | No | | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `{ ariaDescribedby: string | undefined; ids: { root: string; control: string; label: string; errorText: string; helperText: string; }; refs: { rootRef: RefObject ; }; ... 11 more ...; getRequiredIndicatorProps: () => Omit<...>; }` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Select Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Textarea Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `autoresize` | `boolean` | No | Whether the textarea should autoresize | #### Solid **Root 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 | Indicates whether the field is disabled. | | `ids` | `ElementIds` | No | The ids of the field parts. | | `invalid` | `boolean` | No | Indicates whether the field is invalid. | | `readOnly` | `boolean` | No | Indicates whether the field is read-only. | | `required` | `boolean` | No | Indicates whether the field is required. | **ErrorText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'span'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **HelperText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'span'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'input'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'label'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **RequiredIndicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'span'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `fallback` | `number | boolean | Node | ArrayElement | (string & {})` | No | | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `Accessor<{ ariaDescribedby: string; ids: { control: string; label: string; errorText: string; helperText: string; }; refs: { rootRef: Setter ; }; ... 11 more ...; getRequiredIndicatorProps: () => { ...; }; }>` | Yes | | | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Select Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'select'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Textarea Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'textarea'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `autoresize` | `boolean` | No | Whether the textarea should autoresize | #### Vue **Root 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 | Indicates whether the field is disabled. | | `id` | `string` | No | The id of the field. | | `ids` | `ElementIds` | No | The ids of the field parts. | | `invalid` | `boolean` | No | Indicates whether the field is invalid. | | `readOnly` | `boolean` | No | Indicates whether the field is read-only. | | `required` | `boolean` | No | Indicates whether the field is required. | **ErrorText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **HelperText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `modelValue` | `any` | No | | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **RequiredIndicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `{ ariaDescribedby: string | undefined; ids: { control: string; label: string; errorText: string; helperText: string; }; refs: { rootRef: Ref Legend Helper text Error text Legend Helper text Error text Legend Helper text Error text Legend Helper text Error text Legend Fieldset Helper Text Fieldset Error Text Label Field Helper Text Field Error Text Legend Fieldset Helper Text Fieldset Error Text Label Field Helper Text Field Error Text Legend Fieldset Helper Text Fieldset Error Text Label Field Helper Text Field Error Text Personal Information First Name Last Name Email We'll never share your email Please fill out all required fields Legend Fieldset Helper Text Fieldset Error Text Label ✔️ Field Heler Text Field Error Text Legend Fieldset Helper Text Fieldset Error Text Label ✔️ Field Heler Text Field Error Text Legend Fieldset Helper Text Fieldset Error Text Checkbox ✔️ Field Heler Text Field Error Text Legend Helper text Error text Label ✔️ Field Heler Text Field Error Text Legend Helper text Error text Legend Helper text Error text Contact Information Please fill out all required fields External State Management Managed by external fieldset state {#snippet render(fieldset)} ``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ### Input with Select This example shows how to use the `Fieldset` component with `Field.Input` and `Select` to create a interactive phone input component. **Example: phone-input** #### React ```tsx import { Field } from '@ark-ui/react/field' import { Fieldset } from '@ark-ui/react/fieldset' import { Portal } from '@ark-ui/react/portal' import { Select, createListCollection } from '@ark-ui/react/select' import { useRef } from 'react' export const PhoneInput = () => { const extensions = createListCollection({ items: ['+1', '+44', '+49', '+41'], }) const inputRef = useRef{/snippet}Fieldset disabled: {fieldset().disabled}
Fieldset invalid: {fieldset().invalid}
(null) const focusInput = () => { setTimeout(() => { inputRef.current?.focus() }) } return ( Mobile Number {extensions.items.map((item) => ( {item} (null) const focusInput = () => { setTimeout(() => { inputRef()?.focus() }) } return ( Mobile Number {(item) => ( {item()} Mobile Number {{ item }} Mobile Number {#each extensions.items as item} {item} ; }; disabled: boolean; invalid: boolean; getRootProps: () => Omit File Upload Choose file(s) {({ acceptedFiles }) => acceptedFiles.map((file) => ( X File Upload Choose file(s) {(context) => ( {(file) => ( )}Any Icon X File Upload Choose file(s) Generic IconX File Upload Choose file(s) {#snippet render(context)} {#each context().acceptedFiles as file (file.name)} X File Upload Choose file(s) {({ acceptedFiles }) => acceptedFiles.map((file) => ( File Upload Choose file(s) {(context) => ( {(file) => ( )}File Upload Choose file(s) 📄File Upload Choose file(s) {#snippet render(context)} {#each context().acceptedFiles as file (file.name)} File Upload Choose file(s) Clear Files {({ acceptedFiles }) => acceptedFiles.map((file) => ( File Upload Choose file(s) Clear Files {(context) => ( {(file) => ( )}File Upload Choose file(s) Clear Files File Upload Drag your file(s) here Choose file(s) {#snippet render(context)} {#if context().acceptedFiles.length > 0} {/if} {/snippet} {#snippet render(context)} {#each context().acceptedFiles as file (file.name)} X Drag and drop your images here {({ acceptedFiles }) => acceptedFiles.map((file) => ( Drag and drop your images here {(fileUpload) => ( {(file) => ( )}Drag and drop your images here Drag and drop your images here {#snippet render(fileUpload)} {#each fileUpload().acceptedFiles as file (file.name)} Upload Folder {({ acceptedFiles }) => acceptedFiles.map((file) => ( {file.webkitRelativePath ?? file.name} Upload Folder {(fileUpload) => ( {(file) => ( )}{file.webkitRelativePath ?? file.name} Upload Folder {{ file.webkitRelativePath ?? file.name }} Upload Folder {#snippet render(fileUpload)} {#each fileUpload().acceptedFiles as file (file.name)} {file.webkitRelativePath ?? file.name} File Upload (PNG and JPEG only) Drop your files here Select Files {({ acceptedFiles }) => acceptedFiles.map((file) => ( Remove {({ rejectedFiles }) => rejectedFiles.map((fileRejection) => ( File Upload (PNG and JPEG only) Drop your files here Select Files {(context) => ( {(file) => ( )}Remove {(context) => ( {(fileRejection) => ( )}{(error) => {error}}File Upload (PNG and JPEG only) Drop your files here Select Files Remove {{ error }}File Upload (PNG and JPEG only) Drop your files here Select Files {#snippet render(context)} {#each context().acceptedFiles as file (file.name)} Remove {#snippet render(context)} {#each context().rejectedFiles as fileRejection (fileRejection.file.name)} File Upload with Validation Select Files {/* Accepted Files Section */}{/* Rejected Files Section */}✅ Accepted Files
{({ acceptedFiles }) => acceptedFiles.length === 0 ? ( No files uploaded yet) : ( acceptedFiles.map((file) => (Remove ❌ Rejected Files
{({ rejectedFiles }) => rejectedFiles.length === 0 ? ( No rejected files) : ( rejectedFiles.map((fileRejection) => (File Upload with Validation Select Files {/* Accepted Files Section */}{/* Rejected Files Section */}✅ Accepted Files
{(fileUpload) => fileUpload().acceptedFiles.length === 0 ? ( No files uploaded yet) : ({(file) => ( ) }Remove ❌ Rejected Files
{(fileUpload) => fileUpload().rejectedFiles.length === 0 ? ( No rejected files) : ({(fileRejection) => ( ) }{(error) => {errorMessages[error] || `❓ ${error}`}}File Upload with Validation Select Files ✅ Accepted Files
No files uploaded yetPDFRemove ❌ Rejected Files
No rejected filesValidation Errors:{{ errorMessages[error] || `❓ ${error}` }}File Upload with Validation Select Files ✅ Accepted Files
{#snippet render(fileUpload)} {#if fileUpload().acceptedFiles.length === 0} No files uploaded yet{:else} {#each fileUpload().acceptedFiles as file (file.name)}Remove ❌ Rejected Files
{#snippet render(fileUpload)} {#if fileUpload().rejectedFiles.length === 0} No rejected files{:else} {#each fileUpload().rejectedFiles as fileRejection (fileRejection.file.name)}File Upload with Compression Choose Images {({ acceptedFiles }) => acceptedFiles.map((file) => ( Remove File Upload with Compression Choose Images {(fileUpload) => ( {(file) => ( )}Remove File Upload with Compression Choose Images Remove File Upload with Compression Choose Images {#snippet render(fileUpload)} {#each fileUpload().acceptedFiles as file (file.name)} Remove { if (file.name.length > 20) return ['FILE_NAME_TOO_LONG'] return null }} > ) } ``` #### Solid ```tsx import { FileUpload } from '@ark-ui/solid/file-upload' import { FileIcon } from 'lucide-solid' import { For } from 'solid-js' export const WithValidation = () => { return (Choose file(s) {({ acceptedFiles }) => acceptedFiles.map((file) => ( X { if (file.name.length > 20) return ['FILE_NAME_TOO_LONG'] return null }} > ) } ``` #### Vue ```vueChoose file(s) {(context) => ( {(file) => ( )}X Choose file(s) X Choose file(s) {#snippet render(context)} {#each context().acceptedFiles as file (file.name)} X {#snippet render(context)} {#if context().rejectedFiles.length > 0} {/if} {/snippet}Rejected Files:
{#each context().rejectedFiles as rejectedFile}{rejectedFile.file.name} - {rejectedFile.errors[0]}
{/each}Label Select Additional Info Error Info Label Select Additional Info Error Info Label Select Additional Info Error Info Label Select Additional Info Error Info File Upload Drag your file(s) here Choose file(s) {({ acceptedFiles }) => acceptedFiles.map((file) => ( X File Upload Drag your file(s)here Choose file(s) {(context) => ( {(file) => ( )}Any Icon X File Upload Drop your files here Choose file(s) Generic IconX ``` ### Pasting Files Use the `setClipboardFiles` method to enable pasting images directly from the clipboard. > You can access the `fileUpload` store from `FileUpload.Context` as well. **Example: with-paste** #### React ```tsx import { FileUpload, useFileUpload } from '@ark-ui/react/file-upload' import { XIcon } from 'lucide-react' export const WithPaste = () => { const fileUpload = useFileUpload({ maxFiles: 3, accept: 'image/*' }) return (File Upload Drag your file(s) here Choose file(s) {#snippet render(context)} {#each context().acceptedFiles as file (file.name)} X File Upload with Paste {#each fileUpload().acceptedFiles as file (file.name)} X {/* ... */} ``` ### Prevent document drop By default, when the dropzone is active, we prevent accidental navigation when files are dropped outside the dropzone. To prevent this behavior, set the `preventDocumentDrop` prop to `false`. ```tsx{/* ... */} ``` ### Prevent double open When you want to delegate clicking to the trigger and remove the dropzone from the tab order, you can use the `disableClick` prop. This prevents the the file picker from opening twice. ```tsxChoose Files Drag files here` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | trigger | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | #### Svelte **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `accept` | `Record Toggle Panel Floating Panel Some content
Toggle Panel Floating Panel Some content
Toggle Panel Floating Panel Some content
Toggle Panel Floating Panel − □ ↗ × Some content
setSize(e.size)}> ) } ``` #### Solid ```tsx import { FloatingPanel } from '@ark-ui/solid/floating-panel' import { ArrowDownLeft, Maximize2, Minus, XIcon } from 'lucide-solid' import { createSignal } from 'solid-js' import { Portal } from 'solid-js/web' export const ControlledSize = () => { const [size, setSize] = createSignal({ width: 400, height: 300 }) return (Toggle Panel Floating Panel Some content
setSize(e.size)}> ) } ``` #### Vue ```vueToggle Panel Floating Panel Some content
Toggle Panel Floating Panel Some content
Toggle Panel Floating Panel Some content
setPosition(e.position)}> ) } ``` #### Solid ```tsx import { FloatingPanel } from '@ark-ui/solid/floating-panel' import { ArrowDownLeft, Maximize2, Minus, XIcon } from 'lucide-solid' import { createSignal } from 'solid-js' import { Portal } from 'solid-js/web' export const ControlledPosition = () => { const [position, setPosition] = createSignal({ x: 200, y: 200 }) return (Toggle Panel Floating Panel Some content
setPosition(e.position)}> ) } ``` #### Vue ```vueToggle Panel Floating Panel Some content
Toggle Panel Floating Panel Some content
Toggle Panel Floating Panel − □ ↗ × Some content
Position: x={position.x}, y={position.y}
{ if (!triggerRect) return { x: 0, y: 0 } return { x: triggerRect.x + triggerRect.width / 2, y: triggerRect.y + triggerRect.height / 2, } }} > ) ``` #### Solid ```tsx import { FloatingPanel } from '@ark-ui/solid/floating-panel' import { ArrowDownLeft, Maximize2, Minus, XIcon } from 'lucide-solid' import { Portal } from 'solid-js/web' export const AnchorPosition = () => (Toggle Panel Floating Panel Some content
{ if (!triggerRect) return { x: 0, y: 0 } return { x: triggerRect.x + triggerRect.width / 2, y: triggerRect.y + triggerRect.height / 2, } }} > ) ``` #### Vue ```vueToggle Panel Floating Panel Some content
Toggle Panel Floating Panel Some content
{ if (!triggerRect) return { x: 0, y: 0 } return { x: triggerRect.x + triggerRect.width / 2, y: triggerRect.y + triggerRect.height / 2, } }} > ``` ### Controlling the open state To control the open state of the floating panel programmatically, you can pass the `open` and `onOpenChange` prop to the machine. **Example: controlled-open** #### React ```tsx import { FloatingPanel } from '@ark-ui/react/floating-panel' import { Portal } from '@ark-ui/react/portal' import { ArrowDownLeft, Maximize2, Minus, XIcon } from 'lucide-react' import { useState } from 'react' export const ControlledOpen = () => { const [open, setOpen] = useState(false) return (Toggle Panel Floating Panel − □ ↗ × Some content
Anchored to trigger center
setOpen(e.open)}> ) } ``` #### Solid ```tsx import { FloatingPanel } from '@ark-ui/solid/floating-panel' import { ArrowDownLeft, Maximize2, Minus, XIcon } from 'lucide-solid' import { createSignal } from 'solid-js' import { Portal } from 'solid-js/web' export const ControlledOpen = () => { const [open, setOpen] = createSignal(false) return (Toggle Panel Floating Panel Some content
setOpen(e.open)}> ) } ``` #### Vue ```vueToggle Panel Floating Panel Some content
Toggle Panel Floating Panel Some content
Toggle Panel Floating Panel − □ ↗ × Some content
Panel is {open ? 'open' : 'closed'}
console.log('onExitComplete invoked')}> ) ``` #### Solid ```tsx import { FloatingPanel } from '@ark-ui/solid/floating-panel' import { ArrowDownLeft, Maximize2, Minus, XIcon } from 'lucide-solid' import { Portal } from 'solid-js/web' export const LazyMount = () => (Toggle Panel Floating Panel Some content
console.log('onExitComplete invoked')}> ) ``` #### Vue ```vueToggle Panel Floating Panel Some content
Toggle Panel Floating Panel Some content
console.log('onExitComplete invoked')}> ``` ### Context To access the context of the floating panel, you can use the `useFloatingPanelContext` hook or the `FloatingPanel.Context` component. **Example: render-fn** #### React ```tsx import { FloatingPanel } from '@ark-ui/react/floating-panel' import { Portal } from '@ark-ui/react/portal' import { ArrowDownLeft, Maximize2, Minus, XIcon } from 'lucide-react' export const RenderFn = () => (Toggle Panel Floating Panel Some content
Toggle Panel {(floatingPanel) => floatingPanel. is {floatingPanel.open ? 'open' : 'closed'}
}Floating Panel Some content
Toggle Panel {(floatingPanel) => floatingPanel is {floatingPanel().open ? 'open' : 'closed'}
}Floating Panel Some content
floatingPanel is {{ floatingPanel.open ? 'open' : 'closed' }}
Toggle Panel Floating Panel Some content
Toggle Panel {#snippet render(floatingPanel)} Panel is {floatingPanel().open ? 'open' : 'closed'}
{/snippet}Floating Panel − □ ↗ × Some content
` | Yes | | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **StageTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `stage` | `Stage` | Yes | The stage of the panel | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Title Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | floating-panel | | `[data-part]` | trigger | | `[data-state]` | "open" | "closed" | | `[data-dragging]` | Present when in the dragging state | #### Svelte **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `allowOverflow` | `boolean` | No | Whether the panel should be strictly contained within the boundary when dragging | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `closeOnEscape` | `boolean` | No | Whether the panel should close when the escape key is pressed | | `defaultOpen` | `boolean` | No | The initial open state of the panel when rendered. Use when you don't need to control the open state of the panel. | | `defaultPosition` | `Point` | No | The initial position of the panel when rendered. Use when you don't need to control the position of the panel. | | `defaultSize` | `Size` | No | The default size of the panel | | `dir` | `'ltr' | 'rtl'` | No | The document's text/writing direction. | | `disabled` | `boolean` | No | Whether the panel is disabled | | `draggable` | `boolean` | No | Whether the panel is draggable | | `getAnchorPosition` | `(details: AnchorPositionDetails) => Point` | No | Function that returns the initial position of the panel when it is opened. If provided, will be used instead of the default position. | | `getBoundaryEl` | `() => HTMLElement | null` | No | The boundary of the panel. Useful for recalculating the boundary rect when the it is resized. | | `gridSize` | `number` | No | The snap grid for the panel | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ trigger: string; positioner: string; content: string; title: string; header: string }>` | No | The ids of the elements in the floating panel. Useful for composition. | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `lockAspectRatio` | `boolean` | No | Whether the panel is locked to its aspect ratio | | `maxSize` | `Size` | No | The maximum size of the panel | | `minSize` | `Size` | No | The minimum size of the panel | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `onOpenChange` | `(details: OpenChangeDetails) => void` | No | Function called when the panel is opened or closed | | `onPositionChange` | `(details: PositionChangeDetails) => void` | No | Function called when the position of the panel changes via dragging | | `onPositionChangeEnd` | `(details: PositionChangeDetails) => void` | No | Function called when the position of the panel changes via dragging ends | | `onSizeChange` | `(details: SizeChangeDetails) => void` | No | Function called when the size of the panel changes via resizing | | `onSizeChangeEnd` | `(details: SizeChangeDetails) => void` | No | Function called when the size of the panel changes via resizing ends | | `onStageChange` | `(details: StageChangeDetails) => void` | No | Function called when the stage of the panel changes | | `open` | `boolean` | No | The controlled open state of the panel | | `persistRect` | `boolean` | No | Whether the panel size and position should be preserved when it is closed | | `position` | `Point` | No | The controlled position of the panel | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `resizable` | `boolean` | No | Whether the panel is resizable | | `size` | `Size` | No | The size of the panel | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `strategy` | `'absolute' | 'fixed'` | No | The strategy to use for positioning | | `translations` | `IntlTranslations` | No | The translations for the floating panel. | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Body 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. | | `ref` | `Element` | No | | **Body Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | floating-panel | | `[data-part]` | body | | `[data-dragging]` | Present when in the dragging state | | `[data-minimized]` | Present when minimized | | `[data-maximized]` | Present when maximized | | `[data-staged]` | Present when not in default stage | **CloseTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Content 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. | | `ref` | `Element` | No | | **Content Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | floating-panel | | `[data-part]` | content | | `[data-state]` | "open" | "closed" | | `[data-dragging]` | Present when in the dragging state | | `[data-topmost]` | Present when topmost | | `[data-behind]` | Present when not topmost | | `[data-minimized]` | Present when minimized | | `[data-maximized]` | Present when maximized | | `[data-staged]` | Present when not in default stage | **Context Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `render` | `Snippet<[UseFloatingPanelContext]>` | Yes | | **Control 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. | | `ref` | `Element` | No | | **Control Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | floating-panel | | `[data-part]` | control | | `[data-disabled]` | Present when disabled | | `[data-stage]` | The stage of the control | | `[data-minimized]` | Present when minimized | | `[data-maximized]` | Present when maximized | | `[data-staged]` | Present when not in default stage | **DragTrigger 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. | | `ref` | `Element` | No | | **DragTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | floating-panel | | `[data-part]` | drag-trigger | | `[data-disabled]` | Present when disabled | **Header 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. | | `ref` | `Element` | No | | **Header Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | floating-panel | | `[data-part]` | header | | `[data-dragging]` | Present when in the dragging state | | `[data-topmost]` | Present when topmost | | `[data-behind]` | Present when not topmost | | `[data-minimized]` | Present when minimized | | `[data-maximized]` | Present when maximized | | `[data-staged]` | Present when not in default stage | **Positioner 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. | | `ref` | `Element` | No | | **ResizeTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `axis` | `ResizeTriggerAxis` | Yes | The axis of the resize handle | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **ResizeTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | floating-panel | | `[data-part]` | resize-trigger | | `[data-disabled]` | Present when disabled | | `[data-axis]` | The axis to resize | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseFloatingPanelReturn` | Yes | | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **StageTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `stage` | `Stage` | Yes | The stage of the panel | | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Title Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'h2'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | floating-panel | | `[data-part]` | trigger | | `[data-state]` | "open" | "closed" | | `[data-dragging]` | Present when in the dragging state | ### Context These are the properties available when using `FloatingPanel.Context`, `useFloatingPanelContext` hook or `useFloatingPanel` hook. **API:** | Property | Type | Description | |----------|------|-------------| | `open` | `boolean` | Whether the panel is open | | `setOpen` | `(open: boolean) => void` | Function to open or close the panel | | `dragging` | `boolean` | Whether the panel is being dragged | | `resizing` | `boolean` | Whether the panel is being resized | | `position` | `Point` | The position of the panel | | `setPosition` | `(position: Point) => void` | Function to set the position of the panel | | `size` | `Size` | The size of the panel | | `setSize` | `(size: Size) => void` | Function to set the size of the panel | | `minimize` | `VoidFunction` | Function to minimize the panel | | `maximize` | `VoidFunction` | Function to maximize the panel | | `restore` | `VoidFunction` | Function to restore the panel before it was minimized or maximized | | `resizable` | `boolean` | Whether the panel is resizable | | `draggable` | `boolean` | Whether the panel is draggable | # Hover Card ## Anatomy To set up the hover card correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples Learn how to use the `HoverCard` component in your project. Let's take a look at the most basic example: **Example: basic** #### React ```tsx import { HoverCard } from '@ark-ui/react/hover-card' import { Portal } from '@ark-ui/react/portal' export const Basic = () => ( Hover me Hover me Hover me Hover me setOpen(false)}> ) } ``` #### Solid ```tsx import { HoverCard } from '@ark-ui/solid/hover-card' import { createSignal } from 'solid-js' import { Portal } from 'solid-js/web' export const Controlled = () => { const [isOpen, setOpen] = createSignal(false) return ( <>Hover me setOpen(false)}> ) } ``` #### Vue ```vueHover me Hover me Hover me Hover me Hover me Hover me Hover me {(hoverCard) => Hover me {hoverCard.open ? '▲' : '▼'} }{(context) => Hover me {context().open ? '▲' : '▼'} }Hover me {{ hoverCard.open ? '▲' : '▼' }} {#snippet render(hoverCard)} Hover me {hoverCard().open ? '▲' : '▼'} {/snippet}Hover me Hover me Hover me Hover me ` | Yes | | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | hover-card | | `[data-part]` | trigger | | `[data-placement]` | The placement of the trigger | | `[data-state]` | "open" | "closed" | #### Svelte **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `closeDelay` | `number` | No | The duration from when the mouse leaves the trigger or content until the hover card closes. | | `defaultOpen` | `boolean` | No | The initial open state of the hover card when rendered. Use when you don't need to control the open state of the hover card. | | `disabled` | `boolean` | No | Whether the hover card is disabled | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ trigger: string; content: string; positioner: string; arrow: string }>` | No | The ids of the elements in the popover. Useful for composition. | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component | | `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component | | `onOpenChange` | `(details: OpenChangeDetails) => void` | No | Function called when the hover card opens or closes. | | `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component | | `open` | `boolean` | No | The controlled open state of the hover card | | `openDelay` | `number` | No | The duration from when the mouse enters the trigger until the hover card opens. | | `positioning` | `PositioningOptions` | No | The user provided options used to position the popover content | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Arrow 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. | | `ref` | `Element` | No | | **ArrowTip 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. | | `ref` | `Element` | No | | **Content 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. | | `ref` | `Element` | No | | **Content Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | hover-card | | `[data-part]` | content | | `[data-state]` | "open" | "closed" | | `[data-nested]` | popover | | `[data-has-nested]` | popover | | `[data-placement]` | The placement of the content | **Context Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `render` | `Snippet<[UseHoverCardContext]>` | Yes | | **Positioner 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. | | `ref` | `Element` | No | | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseHoverCardReturn` | Yes | | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | hover-card | | `[data-part]` | trigger | | `[data-placement]` | The placement of the trigger | | `[data-state]` | "open" | "closed" | ### Context These are the properties available when using `HoverCard.Context`, `useHoverCardContext` hook or `useHoverCard` hook. **API:** | Property | Type | Description | |----------|------|-------------| | `open` | `boolean` | Whether the hover card is open | | `setOpen` | `(open: boolean) => void` | Function to open the hover card | | `reposition` | `(options?: Partial ) => void` | Function to reposition the popover | # Listbox ## Anatomy To set up the Listbox correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. {/* */} ## Examples ### Basic Here's a basic example of the Listbox component. **Example: basic** #### React ```tsx import { Listbox, createListCollection } from '@ark-ui/react/listbox' export const Basic = () => { const collection = createListCollection({ items: ['React', 'Solid', 'Vue', 'Svelte'] }) return ( Select your Framework {collection.items.map((item) => ( {item} Select your Framework {(item) => ( {item()} Framework {{ item }} Select your Framework {#each collection.items as item} {item} setValue(e.value)} collection={collection}> ) } ``` #### Solid ```tsx import { Listbox, createListCollection } from '@ark-ui/solid/listbox' import { Index, createSignal } from 'solid-js' export const Controlled = () => { const collection = createListCollection({ items: ['React', 'Solid', 'Vue', 'Svelte'] }) const [value, setValue] = createSignal(['React']) return (Select your Framework {collection.items.map((item) => ( {item} setValue(e.value)} collection={collection}> ) } ``` #### Vue ```vueSelect your Framework {(item) => ( {item()} Framework {{ item }} Select your Framework {#each collection.items as item (item)} {item} Select your Framework {collection.items.map((item) => ( {item.label} Select your Framework {(item) => ( {item().label} Select your Framework {{ item.label }} Select your Framework {#each collection.items as item (item.value)} {item.label} Select your Framework {collection.items.map((item) => ( {item} Select your Framework {(item) => ( {item()} Select your Framework {{ item }} Select your Frameworks (Multiple) {#each collection.items as item} {item} ``` ### Grouping The Listbox component supports grouping items. You can use the `groupBy` function to group items based on a specific property. **Example: group** #### React ```tsx import { Listbox, createListCollection } from '@ark-ui/react/listbox' export const Group = () => { const collection = createListCollection({ items: [ { label: 'React', value: 'react', type: 'JS' }, { label: 'Solid', value: 'solid', type: 'JS' }, { label: 'Vue', value: 'vue', type: 'JS' }, { label: 'Panda', value: 'panda', type: 'CSS' }, { label: 'Tailwind', value: 'tailwind', type: 'CSS' }, ], groupBy: (item) => item.type, }) return (Selected: {JSON.stringify(value)}
Select your Frameworks {collection.group().map(([type, group]) => ( {type} {group.map((item) => ({item.label} Select your Frameworks {([type, group]) => ( {type} {(item) => ( {item.label} Select your Frameworks {{ type }} {{ item.label }} Select your Frameworks {#each collection.group() as [type, group]} {type} {#each group as item}{item.label} extends ArkListbox.RootProps {} const Listbox: ArkListbox.RootComponent = (props) => { return {/* ... */} } ``` Then, you can use the `Listbox` component as follows: ```tsx const App = () => { const collection = createListCollection({ initialItems: [ { label: 'React', value: 'react' }, { label: 'Vue', value: 'vue' }, { label: 'Svelte', value: 'svelte' }, ], }) return ({ // this will be strongly typed Array<{ label: string, value: string }> console.log(e.items) }} > {/* ... */} ) } ``` ## API Reference ### Props **Component API Reference** #### React **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `collection` | `ListCollection` | Yes | The collection of items | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `defaultHighlightedValue` | `string` | No | The initial value of the highlighted item when opened. Use when you don't need to control the highlighted value of the listbox. | | `defaultValue` | `string[]` | No | The initial default value of the listbox when rendered. Use when you don't need to control the value of the listbox. | | `deselectable` | `boolean` | No | Whether to disallow empty selection | | `disabled` | `boolean` | No | Whether the listbox is disabled | | `disallowSelectAll` | `boolean` | No | Whether to disallow selecting all items when `meta+a` is pressed | | `highlightedValue` | `string` | No | The controlled key of the highlighted item | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string content: string label: string item: (id: string | number) => string itemGroup: (id: string | number) => string itemGroupLabel: (id: string | number) => string }>` | No | The ids of the elements in the listbox. Useful for composition. | | `loopFocus` | `boolean` | No | Whether to loop the keyboard navigation through the options | | `onHighlightChange` | `(details: HighlightChangeDetails ) => void` | No | The callback fired when the highlighted item changes. | | `onSelect` | `(details: SelectionDetails) => void` | No | Function called when an item is selected | | `onValueChange` | `(details: ValueChangeDetails ) => void` | No | The callback fired when the selected item changes. | | `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the listbox. | | `scrollToIndexFn` | `(details: ScrollToIndexDetails) => void` | No | Function to scroll to a specific index | | `selectionMode` | `SelectionMode` | No | How multiple selection should behave in the listbox. - `single`: The user can select a single item. - `multiple`: The user can select multiple items without using modifier keys. - `extended`: The user can select multiple items by using modifier keys. | | `selectOnHighlight` | `boolean` | No | Whether to select the item when it is highlighted | | `typeahead` | `boolean` | No | Whether to enable typeahead on the listbox | | `value` | `string[]` | No | The controlled keys of the selected items | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | root | | `[data-orientation]` | The orientation of the listbox | | `[data-disabled]` | Present when disabled | **Content Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Content Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | content | | `[data-activedescendant]` | The id the active descendant of the content | | `[data-orientation]` | The orientation of the content | | `[data-layout]` | | | `[data-empty]` | Present when the content is empty | **Empty Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `autoHighlight` | `boolean` | No | Whether to automatically highlight the item when typing | **Input Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | input | | `[data-disabled]` | Present when disabled | **ItemGroupLabel Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemGroup Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemGroup Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | item-group | | `[data-disabled]` | Present when disabled | | `[data-orientation]` | The orientation of the item | | `[data-empty]` | Present when the content is empty | **ItemIndicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemIndicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | item-indicator | | `[data-state]` | "checked" | "unchecked" | **Item Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `highlightOnHover` | `boolean` | No | Whether to highlight the item on hover | | `item` | `any` | No | The item to render | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | item | | `[data-value]` | The value of the item | | `[data-selected]` | Present when selected | | `[data-layout]` | | | `[data-state]` | "checked" | "unchecked" | | `[data-orientation]` | The orientation of the item | | `[data-highlighted]` | Present when highlighted | | `[data-disabled]` | Present when disabled | **ItemText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | item-text | | `[data-state]` | "checked" | "unchecked" | | `[data-disabled]` | Present when disabled | | `[data-highlighted]` | Present when highlighted | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | label | | `[data-disabled]` | Present when disabled | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseListboxReturn ` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ValueText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `placeholder` | `string` | No | Text to display when no value is listboxed. | **ValueText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | value-text | | `[data-disabled]` | Present when disabled | #### Solid **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `collection` | `ListCollection ` | Yes | The collection of items | | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `defaultHighlightedValue` | `string` | No | The initial value of the highlighted item when opened. Use when you don't need to control the highlighted value of the listbox. | | `defaultValue` | `string[]` | No | The initial default value of the listbox when rendered. Use when you don't need to control the value of the listbox. | | `deselectable` | `boolean` | No | Whether to disallow empty selection | | `disabled` | `boolean` | No | Whether the listbox is disabled | | `disallowSelectAll` | `boolean` | No | Whether to disallow selecting all items when `meta+a` is pressed | | `highlightedValue` | `string` | No | The controlled key of the highlighted item | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string content: string label: string item: (id: string | number) => string itemGroup: (id: string | number) => string itemGroupLabel: (id: string | number) => string }>` | No | The ids of the elements in the listbox. Useful for composition. | | `loopFocus` | `boolean` | No | Whether to loop the keyboard navigation through the options | | `onHighlightChange` | `(details: HighlightChangeDetails ) => void` | No | The callback fired when the highlighted item changes. | | `onSelect` | `(details: SelectionDetails) => void` | No | Function called when an item is selected | | `onValueChange` | `(details: ValueChangeDetails ) => void` | No | The callback fired when the selected item changes. | | `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the listbox. | | `scrollToIndexFn` | `(details: ScrollToIndexDetails) => void` | No | Function to scroll to a specific index | | `selectionMode` | `SelectionMode` | No | How multiple selection should behave in the listbox. - `single`: The user can select a single item. - `multiple`: The user can select multiple items without using modifier keys. - `extended`: The user can select multiple items by using modifier keys. | | `selectOnHighlight` | `boolean` | No | Whether to select the item when it is highlighted | | `typeahead` | `boolean` | No | Whether to enable typeahead on the listbox | | `value` | `string[]` | No | The controlled keys of the selected items | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | root | | `[data-orientation]` | The orientation of the listbox | | `[data-disabled]` | Present when disabled | **Content 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. | **Content Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | content | | `[data-activedescendant]` | The id the active descendant of the content | | `[data-orientation]` | The orientation of the content | | `[data-layout]` | | | `[data-empty]` | Present when the content is empty | **Empty 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. | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'input'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `autoHighlight` | `boolean` | No | Whether to automatically highlight the item when typing | **Input Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | input | | `[data-disabled]` | Present when disabled | **ItemGroupLabel 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. | **ItemGroup 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. | **ItemGroup Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | item-group | | `[data-disabled]` | Present when disabled | | `[data-orientation]` | The orientation of the item | | `[data-empty]` | Present when the content is empty | **ItemIndicator 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. | **ItemIndicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | item-indicator | | `[data-state]` | "checked" | "unchecked" | **Item 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. | | `highlightOnHover` | `boolean` | No | Whether to highlight the item on hover | | `item` | `any` | No | The item to render | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | item | | `[data-value]` | The value of the item | | `[data-selected]` | Present when selected | | `[data-layout]` | | | `[data-state]` | "checked" | "unchecked" | | `[data-orientation]` | The orientation of the item | | `[data-highlighted]` | Present when highlighted | | `[data-disabled]` | Present when disabled | **ItemText 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. | **ItemText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | item-text | | `[data-state]` | "checked" | "unchecked" | | `[data-disabled]` | Present when disabled | | `[data-highlighted]` | Present when highlighted | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'label'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | label | | `[data-disabled]` | Present when disabled | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseListboxReturn ` | Yes | | | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ValueText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'span'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `placeholder` | `string` | No | Text to display when no value is selected. | **ValueText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | value-text | | `[data-disabled]` | Present when disabled | #### Vue **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `collection` | `ListCollection ` | Yes | The collection of items | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `defaultHighlightedValue` | `string` | No | The initial value of the highlighted item when opened. Use when you don't need to control the highlighted value of the listbox. | | `defaultValue` | `string[]` | No | The initial default value of the listbox when rendered. Use when you don't need to control the value of the listbox. | | `deselectable` | `boolean` | No | Whether to disallow empty selection | | `disabled` | `boolean` | No | Whether the listbox is disabled | | `disallowSelectAll` | `boolean` | No | Whether to disallow selecting all items when `meta+a` is pressed | | `highlightedValue` | `string` | No | The controlled key of the highlighted item | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string content: string label: string item(id: string | number): string itemGroup(id: string | number): string itemGroupLabel(id: string | number): string }>` | No | The ids of the elements in the listbox. Useful for composition. | | `loopFocus` | `boolean` | No | Whether to loop the keyboard navigation through the options | | `modelValue` | `string[]` | No | The model value of the listbox | | `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the element. | | `scrollToIndexFn` | `(details: ScrollToIndexDetails) => void` | No | Function to scroll to a specific index | | `selectionMode` | `SelectionMode` | No | How multiple selection should behave in the listbox. - `single`: The user can select a single item. - `multiple`: The user can select multiple items without using modifier keys. - `extended`: The user can select multiple items by using modifier keys. | | `selectOnHighlight` | `boolean` | No | Whether to select the item when it is highlighted | | `typeahead` | `boolean` | No | Whether to enable typeahead on the listbox | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | root | | `[data-orientation]` | The orientation of the listbox | | `[data-disabled]` | Present when disabled | **Content Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Content Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | content | | `[data-activedescendant]` | The id the active descendant of the content | | `[data-orientation]` | The orientation of the content | | `[data-layout]` | | | `[data-empty]` | Present when the content is empty | **Empty Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | input | | `[data-disabled]` | Present when disabled | **ItemGroupLabel Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemGroup Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `id` | `string` | No | | **ItemGroup Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | item-group | | `[data-disabled]` | Present when disabled | | `[data-orientation]` | The orientation of the item | | `[data-empty]` | Present when the content is empty | **ItemIndicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemIndicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | item-indicator | | `[data-state]` | "checked" | "unchecked" | **Item Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `highlightOnHover` | `boolean` | No | Whether to highlight the item on hover | | `item` | `any` | No | The item to render | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | item | | `[data-value]` | The value of the item | | `[data-selected]` | Present when selected | | `[data-layout]` | | | `[data-state]` | "checked" | "unchecked" | | `[data-orientation]` | The orientation of the item | | `[data-highlighted]` | Present when highlighted | | `[data-disabled]` | Present when disabled | **ItemText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | item-text | | `[data-state]` | "checked" | "unchecked" | | `[data-disabled]` | Present when disabled | | `[data-highlighted]` | Present when highlighted | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | label | | `[data-disabled]` | Present when disabled | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `ListboxApi ` | Yes | The collection of items | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `defaultHighlightedValue` | `string` | No | The initial value of the highlighted item when opened. Use when you don't need to control the highlighted value of the listbox. | | `defaultValue` | `string[]` | No | The initial default value of the listbox when rendered. Use when you don't need to control the value of the listbox. | | `deselectable` | `boolean` | No | Whether to disallow empty selection | | `disabled` | `boolean` | No | Whether the listbox is disabled | | `disallowSelectAll` | `boolean` | No | Whether to disallow selecting all items when `meta+a` is pressed | | `highlightedValue` | `string` | No | The controlled key of the highlighted item | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string content: string label: string item: (id: string | number) => string itemGroup: (id: string | number) => string itemGroupLabel: (id: string | number) => string }>` | No | The ids of the elements in the listbox. Useful for composition. | | `loopFocus` | `boolean` | No | Whether to loop the keyboard navigation through the options | | `onHighlightChange` | `(details: HighlightChangeDetails ) => void` | No | The callback fired when the highlighted item changes. | | `onSelect` | `(details: SelectionDetails) => void` | No | Function called when an item is selected | | `onValueChange` | `(details: ValueChangeDetails ) => void` | No | The callback fired when the selected item changes. | | `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the listbox. | | `scrollToIndexFn` | `(details: ScrollToIndexDetails) => void` | No | Function to scroll to a specific index | | `selectionMode` | `SelectionMode` | No | How multiple selection should behave in the listbox. - `single`: The user can select a single item. - `multiple`: The user can select multiple items without using modifier keys. - `extended`: The user can select multiple items by using modifier keys. | | `selectOnHighlight` | `boolean` | No | Whether to select the item when it is highlighted | | `typeahead` | `boolean` | No | Whether to enable typeahead on the listbox | | `value` | `string[]` | No | The controlled keys of the selected items | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | root | | `[data-orientation]` | The orientation of the listbox | | `[data-disabled]` | Present when disabled | **Content 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. | | `ref` | `Element` | No | | **Content Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | content | | `[data-activedescendant]` | The id the active descendant of the content | | `[data-orientation]` | The orientation of the content | | `[data-layout]` | | | `[data-empty]` | Present when the content is empty | **Context Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `render` | `Snippet<[UseListboxContext ]>` | Yes | | **Empty 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. | | `ref` | `Element` | No | | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'input'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `autoHighlight` | `boolean` | No | Whether to automatically highlight the item when typing | | `ref` | `Element` | No | | **Input Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | input | | `[data-disabled]` | Present when disabled | **ItemContext Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `render` | `Snippet<[UseListboxItemContext]>` | Yes | | **ItemGroupLabel 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. | | `ref` | `Element` | No | | **ItemGroup 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. | | `ref` | `Element` | No | | **ItemGroup Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | item-group | | `[data-disabled]` | Present when disabled | | `[data-orientation]` | The orientation of the item | | `[data-empty]` | Present when the content is empty | **ItemIndicator 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. | | `ref` | `Element` | No | | **ItemIndicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | item-indicator | | `[data-state]` | "checked" | "unchecked" | **Item 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. | | `highlightOnHover` | `boolean` | No | Whether to highlight the item on hover | | `item` | `any` | No | The item to render | | `ref` | `Element` | No | | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | item | | `[data-value]` | The value of the item | | `[data-selected]` | Present when selected | | `[data-layout]` | | | `[data-state]` | "checked" | "unchecked" | | `[data-orientation]` | The orientation of the item | | `[data-highlighted]` | Present when highlighted | | `[data-disabled]` | Present when disabled | **ItemText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **ItemText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | item-text | | `[data-state]` | "checked" | "unchecked" | | `[data-disabled]` | Present when disabled | | `[data-highlighted]` | Present when highlighted | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'label'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | label | | `[data-disabled]` | Present when disabled | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseListboxReturn ` | Yes | | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ValueText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `placeholder` | `string` | No | Text to display when no value is selected. | **ValueText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | listbox | | `[data-part]` | value-text | | `[data-disabled]` | Present when disabled | ### Context These are the properties available when using `Listbox.Context`, `useListboxContext` hook or `useListbox` hook. **API:** | Property | Type | Description | |----------|------|-------------| | `empty` | `boolean` | Whether the select value is empty | | `highlightedValue` | `string` | The value of the highlighted item | | `highlightedItem` | `V` | The highlighted item | | `highlightValue` | `(value: string) => void` | Function to highlight a value | | `clearHighlightedValue` | `VoidFunction` | Function to clear the highlighted value | | `selectedItems` | `V[]` | The selected items | | `hasSelectedItems` | `boolean` | Whether there's a selected option | | `value` | `string[]` | The selected item keys | | `valueAsString` | `string` | The string representation of the selected items | | `selectValue` | `(value: string) => void` | Function to select a value | | `selectAll` | `VoidFunction` | Function to select all values. **Note**: This should only be called when the selectionMode is `multiple` or `extended`. Otherwise, an exception will be thrown. | | `setValue` | `(value: string[]) => void` | Function to set the value of the select | | `clearValue` | `(value?: string) => void` | Function to clear the value of the select. If a value is provided, it will only clear that value, otherwise, it will clear all values. | | `getItemState` | `(props: ItemProps ) => ItemState` | Returns the state of a select item | | `collection` | `ListCollection ` | Function to toggle the select | | `disabled` | `boolean` | Whether the select is disabled | # Marquee ## Features - Smooth GPU-accelerated animations with seamless looping - Horizontal and vertical scrolling with RTL support - Auto-fill mode to duplicate content - Customizable speed and spacing - Pause on hover/focus with keyboard support - Programmatic control and finite loops ## Anatomy To set up the marquee correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. {/* */} ## Examples Learn how to use the `Marquee` component in your project. Let's take a look at the most basic example: **Example: basic** #### React ```tsx import { Marquee } from '@ark-ui/react/marquee' const items = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry', 'Fig', 'Grape'] export const Basic = () => ( {items.map((item, i) => ( {item} ))}{(item) => {item} }{{ item }} {#each items as item} {item} {/each}{items.map((item, i) => ( {item} ))}{(item) => {item} }{{ item }} {#each items as item} {item} {/each}{items.map((item, i) => ( {item} ))}{(item) => {item} }{{ item }} {#each items as item} {item} {/each}{items.map((item, i) => ( {item} ))}{(item) => {item} }{{ item }} {#each items as item} {item} {/each}) ``` #### Solid ```tsx import { For } from 'solid-js' import { Marquee } from '@ark-ui/solid/marquee' const items = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry', 'Fig', 'Grape'] export const Speed = () => (Slow (25px/s)
{items.map((item, i) => ( {item} ))}Normal (50px/s)
{items.map((item, i) => ( {item} ))}Fast (100px/s)
{items.map((item, i) => ( {item} ))}) ``` #### Vue ```vueSlow (25px/s)
{(item) => {item} }Normal (50px/s)
{(item) => {item} }Fast (100px/s)
{(item) => {item} }``` #### Svelte ```svelteSlow (25px/s)
{{ item }} Normal (50px/s)
{{ item }} Fast (100px/s)
{{ item }} ``` ### Pause on Interaction Enable `pauseOnInteraction` to pause the marquee when users hover or focus on it, improving accessibility: **Example: pause-on-interaction** #### React ```tsx import { Marquee } from '@ark-ui/react/marquee' const items = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry', 'Fig', 'Grape'] export const PauseOnInteraction = () => (Slow (25px/s)
{#each items as item} {item} {/each}Normal (50px/s)
{#each items as item} {item} {/each}Fast (100px/s)
{#each items as item} {item} {/each}{items.map((item, i) => ( {item} ))}{(item) => {item} }{{ item }} {#each items as item} {item} {/each}{items.map((item, i) => ( {item} ))}) } ``` #### Solid ```tsx import { For } from 'solid-js' import { Marquee, useMarquee } from '@ark-ui/solid/marquee' const items = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry', 'Fig', 'Grape'] export const ProgrammaticControl = () => { const marquee = useMarquee() return ( <>{(item) => {item} }) } ``` #### Vue ```vue{{ item }} ``` #### Svelte ```svelte{#each items as item} {item} {/each}``` > If you're using the `Marquee.RootProvider` component, you don't need to use the `Marquee.Root` component. ### Finite Loops Set the `loopCount` prop to run the marquee a specific number of times. Use `onLoopComplete` to track each loop iteration and `onComplete` to know when all loops finish: **Example: finite-loops** #### React ```tsx import { useState } from 'react' import { Marquee } from '@ark-ui/react/marquee' const items = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry', 'Fig', 'Grape'] export const FiniteLoops = () => { const [loopCount, setLoopCount] = useState(0) const [completedCount, setCompletedCount] = useState(0) return ( <>setLoopCount((prev) => prev + 1)} onComplete={() => setCompletedCount((prev) => prev + 1)} > {items.map((item, i) => ( {item} ))}) } ``` #### Solid ```tsx import { For, createSignal } from 'solid-js' import { Marquee } from '@ark-ui/solid/marquee' const items = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry', 'Fig', 'Grape'] export const FiniteLoops = () => { const [loopCount, setLoopCount] = createSignal(0) const [completedCount, setCompletedCount] = createSignal(0) return ( <>Loop completed: {loopCount} times
Animation completed: {completedCount} times
setLoopCount((prev) => prev + 1)} onComplete={() => setCompletedCount((prev) => prev + 1)} > {(item) => {item} }) } ``` #### Vue ```vueLoop completed: {loopCount()} times
Animation completed: {completedCount()} times
{{ item }} ``` #### Svelte ```svelteLoop completed: {{ loopCount }} times
Animation completed: {{ completedCount }} times
loopCount++} onComplete={() => completedCount++}> {#each items as item} {item} {/each}``` ### Edge Gradients Add `Marquee.Edge` components to create fade effects at the start and end of the scrolling area: **Example: with-edges** #### React ```tsx import { Marquee } from '@ark-ui/react/marquee' const items = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry', 'Fig', 'Grape'] export const WithEdges = () => (Loop completed: {loopCount} times
Animation completed: {completedCount} times
{items.map((item, i) => ( {item} ))}{(item) => {item} }{{ item }} {#each items as item} {item} {/each}` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Viewport Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Viewport Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | marquee | | `[data-part]` | | | `[data-orientation]` | The orientation of the viewport | | `[data-side]` | | #### Svelte **Root 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. | | `autoFill` | `boolean` | No | Whether to automatically duplicate content to fill the container. | | `defaultPaused` | `boolean` | No | Whether the marquee is paused by default. | | `delay` | `number` | No | The delay before the animation starts (in seconds). | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string; viewport: string; content: (index: number) => string }>` | No | The ids of the elements in the marquee. Useful for composition. | | `loopCount` | `number` | No | The number of times to loop the animation (0 = infinite). | | `onComplete` | `() => void` | No | Function called when the marquee completes all loops and stops. Only fires for finite loops (loopCount > 0). | | `onLoopComplete` | `() => void` | No | Function called when the marquee completes one loop iteration. | | `onPauseChange` | `(details: PauseStatusDetails) => void` | No | Function called when the pause status changes. | | `paused` | `boolean` | No | Whether the marquee is paused. | | `pauseOnInteraction` | `boolean` | No | Whether to pause the marquee on user interaction (hover, focus). | | `ref` | `Element` | No | | | `reverse` | `boolean` | No | Whether to reverse the animation direction. | | `side` | `Side` | No | The side/direction the marquee scrolls towards. | | `spacing` | `string` | No | The spacing between marquee items. | | `speed` | `number` | No | The speed of the marquee animation in pixels per second. | | `translations` | `IntlTranslations` | No | The localized messages to use. | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | marquee | | `[data-part]` | root | | `[data-state]` | "paused" | "idle" | | `[data-orientation]` | The orientation of the marquee | | `[data-paused]` | Present when paused | **Content 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. | | `ref` | `Element` | No | | **Content Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | marquee | | `[data-part]` | | | `[data-index]` | The index of the item | | `[data-orientation]` | The orientation of the content | | `[data-side]` | | | `[data-reverse]` | | | `[data-clone]` | | **Edge Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `side` | `Side` | Yes | The side where the edge gradient should appear. | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Edge Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | marquee | | `[data-part]` | | | `[data-side]` | | | `[data-orientation]` | The orientation of the edge | **Item 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. | | `ref` | `Element` | No | | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseMarqueeReturn` | Yes | | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Viewport 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. | | `ref` | `Element` | No | | **Viewport Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | marquee | | `[data-part]` | | | `[data-orientation]` | The orientation of the viewport | | `[data-side]` | | ### Context These are the properties available when using `Marquee.Context`, `useMarqueeContext` hook or `useMarquee` hook. **API:** | Property | Type | Description | |----------|------|-------------| | `paused` | `boolean` | Whether the marquee is currently paused. | | `orientation` | `"horizontal" | "vertical"` | The current orientation of the marquee. | | `side` | `Side` | The current side/direction of the marquee. | | `multiplier` | `number` | The multiplier for auto-fill. Indicates how many times to duplicate content. When autoFill is enabled and content is smaller than container, this returns the number of additional copies needed. Otherwise returns 1. | | `contentCount` | `number` | The total number of content elements to render (original + clones). Use this value when rendering your content in a loop. | | `pause` | `VoidFunction` | Pause the marquee animation. | | `resume` | `VoidFunction` | Resume the marquee animation. | | `togglePause` | `VoidFunction` | Toggle the pause state. | | `restart` | `VoidFunction` | Restart the marquee animation from the beginning. | ## Accessibility The Marquee component is built with accessibility in mind: - Uses appropriate ARIA attributes: `role="region"` and `aria-roledescription="marquee"` - Cloned content for seamless looping is marked with `aria-hidden="true"` to avoid confusion for screen readers - Automatically respects user motion preferences via `prefers-reduced-motion` - Supports keyboard interaction when `pauseOnInteraction` is enabled - Allows users to pause animations on hover or focus for better readability # Menu ## Anatomy To set up the menu correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples Learn how to use the `Menu` component in your project. Let's take a look at the most basic example: **Example: basic** #### React ```tsx import { Menu } from '@ark-ui/react/menu' export const Basic = () => ( Open menu ➡️ React Solid Vue Svelte Open menu ➡️ React Solid Vue Open menu ➡️ React Solid Vue Open menu React Solid Svelte Vue Open menu ➡️ React Solid Vue Svelte console.log(id)}> ) } ``` #### Vue ```vueOpen menu ➡️ React Solid Vue Open menu React Solid Vue Menu is {open ? 'open' : 'closed'}Open menu React Solid Svelte Vue Open menu JS Frameworks React Solid Vue Svelte CSS Frameworks Panda Tailwind Open menu JS Frameworks React Solid Vue CSS Frameworks Panda Tailwind Open menu JS Frameworks React Solid Vue CSS Frameworks Panda Tailwind Open menu JS Frameworks React Solid Vue Svelte CSS Frameworks Panda Tailwind Open menu React Solid Vue Svelte Open menu React Solid Vue Svelte Open menu React Solid Vue Open menu React Solid Vue Svelte Open menu Documentation GitHub Twitter Open menu }> Documentation }> GitHub }> Twitter Open menu Documentation GitHub Twitter Open menu {#snippet asChild(itemProps)} Documentation {/snippet} {#snippet asChild(itemProps)} GitHub {/snippet} {#snippet asChild(itemProps)} Twitter {/snippet} Right click me React Solid Vue Svelte Right click me React Solid Vue Right click me React Solid Vue Right click me React Solid Vue Svelte Open menu JS Frameworks React Solid Vue Svelte CSS Frameworks Panda Tailwind Open menu JS Frameworks React Solid Vue CSS Frameworks Panda Tailwind Open menu JS Frameworks React Solid Vue CSS Frameworks Panda Tailwind Open menu JS Frameworks React Solid Vue Svelte CSS Frameworks Panda Tailwind Open menu ✅ Check me Open menu ✅ Check me Open menu ✅ Check me Open menu ✅ Check me Open menu setValue(e.value)}> JS Frameworks {['React', 'Solid', 'Vue', 'Svelte'].map((framework) => (✅ {framework} Open menu setValue(e.value)}> JS Frameworks {(framework) => ( ✅ {framework()} Open menu JS Frameworks ✅ {{ item }} Open menu JS Frameworks {#each frameworks as framework (framework)}✅ {framework} Open menu ➡️ React Solid Vue Svelte Open menu ➡️ React Solid Vue Svelte Open menu ➡️ React Solid Vue Menu is {menu().api.open ? 'open' : 'closed'}Open menu React Solid Vue Svelte Custom Item // ✅ Do thisCustom Item ``` ### Menu items as links To render a menu item as a link, render the link as the menu item itself using the `asChild` prop, not as a child of the menu item. > This pattern ensures the link element receives the correct ARIA attributes and keyboard interactions from the menu > item. Here's an example of a reusable `MenuItemLink` component: ```tsx interface MenuItemLinkProps extends Menu.ItemProps { href?: string target?: string } export const MenuItemLink = (props: MenuItemLinkProps) => { const { href, target, children, ...rest } = props return ({children} ) } ``` ## API Reference ### Props **Component API Reference** #### React **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `anchorPoint` | `Point` | No | The positioning point for the menu. Can be set by the context menu trigger or the button trigger. | | `aria-label` | `string` | No | The accessibility label for the menu | | `closeOnSelect` | `boolean` | No | Whether to close the menu when an option is selected | | `composite` | `boolean` | No | Whether the menu is a composed with other composite widgets like a combobox or tabs | | `defaultHighlightedValue` | `string` | No | The initial highlighted value of the menu item when rendered. Use when you don't need to control the highlighted value of the menu item. | | `defaultOpen` | `boolean` | No | The initial open state of the menu when rendered. Use when you don't need to control the open state of the menu. | | `highlightedValue` | `string` | No | The controlled highlighted value of the menu item. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ trigger: string contextTrigger: string content: string groupLabel: (id: string) => string group: (id: string) => string positioner: string arrow: string }>` | No | The ids of the elements in the menu. Useful for composition. | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `loopFocus` | `boolean` | No | Whether to loop the keyboard navigation. | | `navigate` | `(details: NavigateDetails) => void` | No | Function to navigate to the selected item if it's an anchor element | | `onEscapeKeyDown` | `(event: KeyboardEvent) => void` | No | Function called when the escape key is pressed | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component | | `onHighlightChange` | `(details: HighlightChangeDetails) => void` | No | Function called when the highlighted menu item changes. | | `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component | | `onOpenChange` | `(details: OpenChangeDetails) => void` | No | Function called when the menu opens or closes | | `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component | | `onRequestDismiss` | `(event: LayerDismissEvent) => void` | No | Function called when this layer is closed due to a parent layer being closed | | `onSelect` | `(details: SelectionDetails) => void` | No | Function called when a menu item is selected. | | `open` | `boolean` | No | The controlled open state of the menu | | `positioning` | `PositioningOptions` | No | The options used to dynamically position the menu | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `typeahead` | `boolean` | No | Whether the pressing printable characters should trigger typeahead navigation | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Arrow Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ArrowTip Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **CheckboxItem Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `checked` | `boolean` | Yes | Whether the option is checked | | `value` | `string` | Yes | The value of the option | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `closeOnSelect` | `boolean` | No | Whether the menu should be closed when the option is selected. | | `disabled` | `boolean` | No | Whether the menu item is disabled | | `onCheckedChange` | `(checked: boolean) => void` | No | Function called when the option state is changed | | `valueText` | `string` | No | The textual value of the option. Used in typeahead navigation of the menu. If not provided, the text content of the menu item will be used. | **Content Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Content Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | menu | | `[data-part]` | content | | `[data-state]` | "open" | "closed" | | `[data-nested]` | menu | | `[data-has-nested]` | menu | | `[data-placement]` | The placement of the content | **ContextTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ContextTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | menu | | `[data-part]` | context-trigger | | `[data-state]` | "open" | "closed" | **Indicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Indicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | menu | | `[data-part]` | indicator | | `[data-state]` | "open" | "closed" | **ItemGroupLabel Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemGroup Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemIndicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemIndicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | menu | | `[data-part]` | item-indicator | | `[data-disabled]` | Present when disabled | | `[data-highlighted]` | Present when highlighted | | `[data-state]` | "checked" | **Item Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `string` | Yes | The unique value of the menu item option. | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `closeOnSelect` | `boolean` | No | Whether the menu should be closed when the option is selected. | | `disabled` | `boolean` | No | Whether the menu item is disabled | | `onSelect` | `VoidFunction` | No | The function to call when the item is selected | | `valueText` | `string` | No | The textual value of the option. Used in typeahead navigation of the menu. If not provided, the text content of the menu item will be used. | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | menu | | `[data-part]` | item | | `[data-disabled]` | Present when disabled | | `[data-highlighted]` | Present when highlighted | | `[data-value]` | The value of the item | | `[data-valuetext]` | The human-readable value | **ItemText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | menu | | `[data-part]` | item-text | | `[data-disabled]` | Present when disabled | | `[data-highlighted]` | Present when highlighted | | `[data-state]` | "checked" | **Positioner Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **RadioItemGroup Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `onValueChange` | `(e: ValueChangeDetails) => void` | No | | | `value` | `string` | No | | **RadioItem Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `string` | Yes | The value of the option | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `closeOnSelect` | `boolean` | No | Whether the menu should be closed when the option is selected. | | `disabled` | `boolean` | No | Whether the menu item is disabled | | `valueText` | `string` | No | The textual value of the option. Used in typeahead navigation of the menu. If not provided, the text content of the menu item will be used. | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseMenuReturn` | Yes | | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Separator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **TriggerItem Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | menu | | `[data-part]` | trigger | | `[data-placement]` | The placement of the trigger | | `[data-state]` | "open" | "closed" | #### Solid **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `anchorPoint` | `Point` | No | The positioning point for the menu. Can be set by the context menu trigger or the button trigger. | | `aria-label` | `string` | No | The accessibility label for the menu | | `closeOnSelect` | `boolean` | No | Whether to close the menu when an option is selected | | `composite` | `boolean` | No | Whether the menu is a composed with other composite widgets like a combobox or tabs | | `defaultHighlightedValue` | `string` | No | The initial highlighted value of the menu item when rendered. Use when you don't need to control the highlighted value of the menu item. | | `defaultOpen` | `boolean` | No | The initial open state of the menu when rendered. Use when you don't need to control the open state of the menu. | | `highlightedValue` | `string` | No | The controlled highlighted value of the menu item. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ trigger: string contextTrigger: string content: string groupLabel: (id: string) => string group: (id: string) => string positioner: string arrow: string }>` | No | The ids of the elements in the menu. Useful for composition. | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `loopFocus` | `boolean` | No | Whether to loop the keyboard navigation. | | `navigate` | `(details: NavigateDetails) => void` | No | Function to navigate to the selected item if it's an anchor element | | `onEscapeKeyDown` | `(event: KeyboardEvent) => void` | No | Function called when the escape key is pressed | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component | | `onHighlightChange` | `(details: HighlightChangeDetails) => void` | No | Function called when the highlighted menu item changes. | | `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component | | `onOpenChange` | `(details: OpenChangeDetails) => void` | No | Function called when the menu opens or closes | | `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component | | `onRequestDismiss` | `(event: LayerDismissEvent) => void` | No | Function called when this layer is closed due to a parent layer being closed | | `onSelect` | `(details: SelectionDetails) => void` | No | Function called when a menu item is selected. | | `open` | `boolean` | No | The controlled open state of the menu | | `positioning` | `PositioningOptions` | No | The options used to dynamically position the menu | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `typeahead` | `boolean` | No | Whether the pressing printable characters should trigger typeahead navigation | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Arrow 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. | **ArrowTip 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. | **CheckboxItem Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `checked` | `boolean` | Yes | Whether the option is checked | | `value` | `string` | Yes | The value of the option | | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `closeOnSelect` | `boolean` | No | Whether the menu should be closed when the option is selected. | | `disabled` | `boolean` | No | Whether the menu item is disabled | | `onCheckedChange` | `(checked: boolean) => void` | No | Function called when the option state is changed | | `valueText` | `string` | No | The textual value of the option. Used in typeahead navigation of the menu. If not provided, the text content of the menu item will be used. | **Content 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. | **Content Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | menu | | `[data-part]` | content | | `[data-state]` | "open" | "closed" | | `[data-nested]` | menu | | `[data-has-nested]` | menu | | `[data-placement]` | The placement of the content | **ContextTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ContextTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | menu | | `[data-part]` | context-trigger | | `[data-state]` | "open" | "closed" | **Indicator 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. | **Indicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | menu | | `[data-part]` | indicator | | `[data-state]` | "open" | "closed" | **ItemGroupLabel 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. | **ItemGroup 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. | **ItemIndicator 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. | **ItemIndicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | menu | | `[data-part]` | item-indicator | | `[data-disabled]` | Present when disabled | | `[data-highlighted]` | Present when highlighted | | `[data-state]` | "checked" | **Item Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `string` | Yes | The unique value of the menu item option. | | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `closeOnSelect` | `boolean` | No | Whether the menu should be closed when the option is selected. | | `disabled` | `boolean` | No | Whether the menu item is disabled | | `onSelect` | `VoidFunction` | No | The function to call when the item is selected | | `valueText` | `string` | No | The textual value of the option. Used in typeahead navigation of the menu. If not provided, the text content of the menu item will be used. | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | menu | | `[data-part]` | item | | `[data-disabled]` | Present when disabled | | `[data-highlighted]` | Present when highlighted | | `[data-value]` | The value of the item | | `[data-valuetext]` | The human-readable value | **ItemText 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. | **ItemText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | menu | | `[data-part]` | item-text | | `[data-disabled]` | Present when disabled | | `[data-highlighted]` | Present when highlighted | | `[data-state]` | "checked" | **Positioner 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. | **RadioItemGroup 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. | | `onValueChange` | `(e: ValueChangeDetails) => void` | No | | | `value` | `string` | No | | **RadioItem Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `string` | Yes | The value of the option | | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `closeOnSelect` | `boolean` | No | Whether the menu should be closed when the option is selected. | | `disabled` | `boolean` | No | Whether the menu item is disabled | | `valueText` | `string` | No | The textual value of the option. Used in typeahead navigation of the menu. If not provided, the text content of the menu item will be used. | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseMenuReturn` | Yes | | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Separator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'hr'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **TriggerItem 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. | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | menu | | `[data-part]` | trigger | | `[data-placement]` | The placement of the trigger | | `[data-state]` | "open" | "closed" | #### Vue **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `anchorPoint` | `Point` | No | The positioning point for the menu. Can be set by the context menu trigger or the button trigger. | | `aria-label` | `string` | No | The accessibility label for the menu | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `closeOnSelect` | `boolean` | No | Whether to close the menu when an option is selected | | `composite` | `boolean` | No | Whether the menu is a composed with other composite widgets like a combobox or tabs | | `defaultHighlightedValue` | `string` | No | The initial highlighted value of the menu item when rendered. Use when you don't need to control the highlighted value of the menu item. | | `defaultOpen` | `boolean` | No | The initial open state of the menu when rendered. Use when you don't need to control the open state of the menu. | | `highlightedValue` | `string` | No | The controlled highlighted value of the menu item. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ trigger: string contextTrigger: string content: string groupLabel(id: string): string group(id: string): string positioner: string arrow: string }>` | No | The ids of the elements in the menu. Useful for composition. | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `loopFocus` | `boolean` | No | Whether to loop the keyboard navigation. | | `navigate` | `(details: NavigateDetails) => void` | No | Function to navigate to the selected item if it's an anchor element | | `open` | `boolean` | No | The controlled open state of the menu | | `positioning` | `PositioningOptions` | No | The options used to dynamically position the menu | | `typeahead` | `boolean` | No | Whether the pressing printable characters should trigger typeahead navigation | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Arrow Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ArrowTip Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **CheckboxItem Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `checked` | `boolean` | Yes | Whether the option is checked | | `value` | `string` | Yes | The value of the option | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `closeOnSelect` | `boolean` | No | Whether the menu should be closed when the option is selected. | | `disabled` | `boolean` | No | Whether the menu item is disabled | | `valueText` | `string` | No | The textual value of the option. Used in typeahead navigation of the menu. If not provided, the text content of the menu item will be used. | **Content Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Content Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | menu | | `[data-part]` | content | | `[data-state]` | "open" | "closed" | | `[data-nested]` | menu | | `[data-has-nested]` | menu | | `[data-placement]` | The placement of the content | **ContextTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ContextTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | menu | | `[data-part]` | context-trigger | | `[data-state]` | "open" | "closed" | **Indicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Indicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | menu | | `[data-part]` | indicator | | `[data-state]` | "open" | "closed" | **ItemGroupLabel Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemGroup Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `id` | `string` | No | The `id` of the element that provides accessibility label to the option group | **ItemIndicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemIndicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | menu | | `[data-part]` | item-indicator | | `[data-disabled]` | Present when disabled | | `[data-highlighted]` | Present when highlighted | | `[data-state]` | "checked" | **Item Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `string` | Yes | The unique value of the menu item option. | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `closeOnSelect` | `boolean` | No | Whether the menu should be closed when the option is selected. | | `disabled` | `boolean` | No | Whether the menu item is disabled | | `valueText` | `string` | No | The textual value of the option. Used in typeahead navigation of the menu. If not provided, the text content of the menu item will be used. | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | menu | | `[data-part]` | item | | `[data-disabled]` | Present when disabled | | `[data-highlighted]` | Present when highlighted | | `[data-value]` | The value of the item | | `[data-valuetext]` | The human-readable value | **ItemText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | menu | | `[data-part]` | item-text | | `[data-disabled]` | Present when disabled | | `[data-highlighted]` | Present when highlighted | | `[data-state]` | "checked" | **Positioner Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **RadioItemGroup Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `id` | `string` | No | | | `modelValue` | `string` | No | | **RadioItem Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `string` | Yes | The value of the option | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `closeOnSelect` | `boolean` | No | Whether the menu should be closed when the option is selected. | | `disabled` | `boolean` | No | Whether the menu item is disabled | | `valueText` | `string` | No | The textual value of the option. Used in typeahead navigation of the menu. If not provided, the text content of the menu item will be used. | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseMenuReturn` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Separator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **TriggerItem Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | menu | | `[data-part]` | trigger | | `[data-placement]` | The placement of the trigger | | `[data-state]` | "open" | "closed" | #### Svelte **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `anchorPoint` | `Point` | No | The positioning point for the menu. Can be set by the context menu trigger or the button trigger. | | `aria-label` | `string` | No | The accessibility label for the menu | | `closeOnSelect` | `boolean` | No | Whether to close the menu when an option is selected | | `composite` | `boolean` | No | Whether the menu is a composed with other composite widgets like a combobox or tabs | | `defaultHighlightedValue` | `string` | No | The initial highlighted value of the menu item when rendered. Use when you don't need to control the highlighted value of the menu item. | | `defaultOpen` | `boolean` | No | The initial open state of the menu when rendered. Use when you don't need to control the open state of the menu. | | `highlightedValue` | `string` | No | The controlled highlighted value of the menu item. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ trigger: string contextTrigger: string content: string groupLabel: (id: string) => string group: (id: string) => string positioner: string arrow: string }>` | No | The ids of the elements in the menu. Useful for composition. | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `loopFocus` | `boolean` | No | Whether to loop the keyboard navigation. | | `navigate` | `(details: NavigateDetails) => void` | No | Function to navigate to the selected item if it's an anchor element | | `onEscapeKeyDown` | `(event: KeyboardEvent) => void` | No | Function called when the escape key is pressed | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component | | `onHighlightChange` | `(details: HighlightChangeDetails) => void` | No | Function called when the highlighted menu item changes. | | `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component | | `onOpenChange` | `(details: OpenChangeDetails) => void` | No | Function called when the menu opens or closes | | `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component | | `onRequestDismiss` | `(event: LayerDismissEvent) => void` | No | Function called when this layer is closed due to a parent layer being closed | | `onSelect` | `(details: SelectionDetails) => void` | No | Function called when a menu item is selected. | | `open` | `boolean` | No | The controlled open state of the menu | | `positioning` | `PositioningOptions` | No | The options used to dynamically position the menu | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `typeahead` | `boolean` | No | Whether the pressing printable characters should trigger typeahead navigation | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Arrow 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. | | `ref` | `Element` | No | | **ArrowTip 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. | | `ref` | `Element` | No | | **CheckboxItem Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `checked` | `boolean` | Yes | Whether the option is checked | | `value` | `string` | Yes | The value of the option | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `closeOnSelect` | `boolean` | No | Whether the menu should be closed when the option is selected. | | `disabled` | `boolean` | No | Whether the menu item is disabled | | `onCheckedChange` | `(checked: boolean) => void` | No | Function called when the option state is changed | | `ref` | `Element` | No | | | `valueText` | `string` | No | The textual value of the option. Used in typeahead navigation of the menu. If not provided, the text content of the menu item will be used. | **Content 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. | | `ref` | `Element` | No | | **Content Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | menu | | `[data-part]` | content | | `[data-state]` | "open" | "closed" | | `[data-nested]` | menu | | `[data-has-nested]` | menu | | `[data-placement]` | The placement of the content | **Context Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `render` | `Snippet<[UseMenuContext]>` | Yes | | **ContextTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **ContextTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | menu | | `[data-part]` | context-trigger | | `[data-state]` | "open" | "closed" | **Indicator 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. | | `ref` | `Element` | No | | **Indicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | menu | | `[data-part]` | indicator | | `[data-state]` | "open" | "closed" | **ItemContext Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `render` | `Snippet<[UseMenuItemContext]>` | Yes | | **ItemGroupLabel 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. | | `ref` | `Element` | No | | **ItemGroup 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. | | `id` | `string` | No | The `id` of the element that provides accessibility label to the option group | | `ref` | `Element` | No | | **ItemIndicator 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. | | `ref` | `Element` | No | | **ItemIndicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | menu | | `[data-part]` | item-indicator | | `[data-disabled]` | Present when disabled | | `[data-highlighted]` | Present when highlighted | | `[data-state]` | "checked" | **Item Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `string` | Yes | The unique value of the menu item option. | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `closeOnSelect` | `boolean` | No | Whether the menu should be closed when the option is selected. | | `disabled` | `boolean` | No | Whether the menu item is disabled | | `onSelect` | `VoidFunction` | No | The function to call when the item is selected | | `ref` | `Element` | No | | | `valueText` | `string` | No | The textual value of the option. Used in typeahead navigation of the menu. If not provided, the text content of the menu item will be used. | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | menu | | `[data-part]` | item | | `[data-disabled]` | Present when disabled | | `[data-highlighted]` | Present when highlighted | | `[data-value]` | The value of the item | | `[data-valuetext]` | The human-readable value | **ItemText 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. | | `ref` | `Element` | No | | **ItemText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | menu | | `[data-part]` | item-text | | `[data-disabled]` | Present when disabled | | `[data-highlighted]` | Present when highlighted | | `[data-state]` | "checked" | **Positioner 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. | | `ref` | `Element` | No | | **RadioItemGroup 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. | | `id` | `string` | No | | | `onValueChange` | `(e: ValueChangeDetails) => void` | No | | | `ref` | `Element` | No | | | `value` | `string` | No | | **RadioItem Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `string` | Yes | The value of the option | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `closeOnSelect` | `boolean` | No | Whether the menu should be closed when the option is selected. | | `disabled` | `boolean` | No | Whether the menu item is disabled | | `ref` | `Element` | No | | | `valueText` | `string` | No | The textual value of the option. Used in typeahead navigation of the menu. If not provided, the text content of the menu item will be used. | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseMenuReturn` | Yes | | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Separator 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. | | `ref` | `Element` | No | | **TriggerItem 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. | | `ref` | `Element` | No | | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | menu | | `[data-part]` | trigger | | `[data-placement]` | The placement of the trigger | | `[data-state]` | "open" | "closed" | ### Context These are the properties available when using `Menu.Context`, `useMenuContext` hook or `useMenu` hook. **API:** | Property | Type | Description | |----------|------|-------------| | `open` | `boolean` | Whether the menu is open | | `setOpen` | `(open: boolean) => void` | Function to open or close the menu | | `highlightedValue` | `string` | The id of the currently highlighted menuitem | | `setHighlightedValue` | `(value: string) => void` | Function to set the highlighted menuitem | | `setParent` | `(parent: ParentMenuService) => void` | Function to register a parent menu. This is used for submenus | | `setChild` | `(child: ChildMenuService) => void` | Function to register a child menu. This is used for submenus | | `reposition` | `(options?: Partial) => void` | Function to reposition the popover | | `getOptionItemState` | `(props: OptionItemProps) => OptionItemState` | Returns the state of the option item | | `getItemState` | `(props: ItemProps) => ItemState` | Returns the state of the menu item | | `addItemListener` | `(props: ItemListenerProps) => VoidFunction` | Setup the custom event listener for item selection event | ## Accessibility Complies with the [Menu WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/). ### Keyboard Support **`Space`** Description: Activates/Selects the highlighted item **`Enter`** Description: Activates/Selects the highlighted item **`ArrowDown`** Description: Highlights the next item in the menu **`ArrowUp`** Description: Highlights the previous item in the menu **`ArrowRight + ArrowLeft`** Description: When focus is on trigger, opens or closes the submenu depending on reading direction. **`Esc`** Description: Closes the menu and moves focus to the trigger # Number Input ## Anatomy To set up the number input correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples Learn how to use the `NumberInput` component in your project. Let's take a look at the most basic example: **Example: basic** #### React ```tsx import { NumberInput } from '@ark-ui/react/number-input' export const Basic = () => ( Label -1 +1 Label -1 +1 Label -1 +1 Count - + Label -1 +1 Label -1 +1 Label -1 +1 Label -1 +1 Label -1 +1 Label -1 +1 Label -1 +1 Label -1 +1 Label -1 +1 Label -1 +1 Label -1 +1 Label -1 +1 Label -1 +1 Label -1 +1 Label -1 +1 Label -1 +1 Label -1 +1 Label -1 +1 Label -1 +1 Label -1 +1 Label -1 +1 Label -1 +1 Label -1 +1 Label -1 +1 Label -1 +1 Label -1 +1 Label -1 +1 Label -1 +1 Label -1 +1 Additional Info Error Info Label -1 +1 Additional Info Error Info Label -1 +1 Additional Info Error Info Label -1 +1 Additional Info Error Info Label -1 +1 Label -1 +1 Label -1 +1 Count - + ` element and displays a custom cursor element during scrubbing interactions. This component utilizes the [Pointer Lock API](https://developer.mozilla.org/en-US/docs/Web/API/Pointer_Lock_API) for smooth dragging interactions. > **Note:** Browsers may show a notification when the Pointer Lock API is activated. The scrubber is automatically > disabled in Safari to prevent layout shifts. ### Controlling the value When controlling the NumberInput component, it's recommended to use string values instead of converting to numbers. This is especially important when using `formatOptions` for currency or locale-specific formatting. ```tsx const [value, setValue] = useState('0')setValue(details.value)}> {/* ... */} ``` Converting values to numbers can cause issues with locale-specific formatting, particularly for currencies that use different decimal and thousands separators (e.g., `1.523,30` vs `1,523.30`). By keeping values as strings, you preserve the correct formatting and avoid parsing issues. If you need to submit a numeric value in your form, use a hidden input that reads `valueAsNumber` from `NumberInput.Context`: ```tsxsetValue(details.value)}> ``` ## API Reference ### Props **Component API Reference** #### React **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `allowMouseWheel` | `boolean` | No | Whether to allow mouse wheel to change the value | | `allowOverflow` | `boolean` | No | Whether to allow the value overflow the min/max range | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `clampValueOnBlur` | `boolean` | No | Whether to clamp the value when the input loses focus (blur) | | `defaultValue` | `string` | No | The initial value of the input when rendered. Use when you don't need to control the value of the input. | | `disabled` | `boolean` | No | Whether the number input is disabled. | | `focusInputOnChange` | `boolean` | No | Whether to focus input when the value changes | | `form` | `string` | No | The associate form of the input element. | | `formatOptions` | `NumberFormatOptions` | No | The options to pass to the `Intl.NumberFormat` constructor | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string label: string input: string incrementTrigger: string decrementTrigger: string scrubber: string }>` | No | The ids of the elements in the number input. Useful for composition. | | `inputMode` | `InputMode` | No | Hints at the type of data that might be entered by the user. It also determines the type of keyboard shown to the user on mobile devices | | `invalid` | `boolean` | No | Whether the number input value is invalid. | | `locale` | `string` | No | The current locale. Based on the BCP 47 definition. | | `max` | `number` | No | The maximum value of the number input | | `min` | `number` | No | The minimum value of the number input | | `name` | `string` | No | The name attribute of the number input. Useful for form submission. | | `onFocusChange` | `(details: FocusChangeDetails) => void` | No | Function invoked when the number input is focused | | `onValueChange` | `(details: ValueChangeDetails) => void` | No | Function invoked when the value changes | | `onValueInvalid` | `(details: ValueInvalidDetails) => void` | No | Function invoked when the value overflows or underflows the min/max range | | `pattern` | `string` | No | The pattern used to check the element's value against | | `readOnly` | `boolean` | No | Whether the number input is readonly | | `required` | `boolean` | No | Whether the number input is required | | `spinOnPress` | `boolean` | No | Whether to spin the value when the increment/decrement button is pressed | | `step` | `number` | No | The amount to increment or decrement the value by | | `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states | | `value` | `string` | No | The controlled value of the input | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | root | | `[data-disabled]` | Present when disabled | | `[data-focus]` | Present when focused | | `[data-invalid]` | Present when invalid | | `[data-scrubbing]` | | **Control Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Control Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | control | | `[data-focus]` | Present when focused | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-scrubbing]` | | **DecrementTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **DecrementTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | decrement-trigger | | `[data-disabled]` | Present when disabled | | `[data-scrubbing]` | | **IncrementTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **IncrementTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | increment-trigger | | `[data-disabled]` | Present when disabled | | `[data-scrubbing]` | | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | input | | `[data-invalid]` | Present when invalid | | `[data-disabled]` | Present when disabled | | `[data-scrubbing]` | | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | label | | `[data-disabled]` | Present when disabled | | `[data-focus]` | Present when focused | | `[data-invalid]` | Present when invalid | | `[data-required]` | Present when required | | `[data-scrubbing]` | | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseNumberInputReturn` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Scrubber Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Scrubber Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | scrubber | | `[data-disabled]` | Present when disabled | | `[data-scrubbing]` | | **ValueText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ValueText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | value-text | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-focus]` | Present when focused | | `[data-scrubbing]` | | #### Solid **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `allowMouseWheel` | `boolean` | No | Whether to allow mouse wheel to change the value | | `allowOverflow` | `boolean` | No | Whether to allow the value overflow the min/max range | | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `clampValueOnBlur` | `boolean` | No | Whether to clamp the value when the input loses focus (blur) | | `defaultValue` | `string` | No | The initial value of the input when rendered. Use when you don't need to control the value of the input. | | `disabled` | `boolean` | No | Whether the number input is disabled. | | `focusInputOnChange` | `boolean` | No | Whether to focus input when the value changes | | `form` | `string` | No | The associate form of the input element. | | `formatOptions` | `NumberFormatOptions` | No | The options to pass to the `Intl.NumberFormat` constructor | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string label: string input: string incrementTrigger: string decrementTrigger: string scrubber: string }>` | No | The ids of the elements in the number input. Useful for composition. | | `inputMode` | `InputMode` | No | Hints at the type of data that might be entered by the user. It also determines the type of keyboard shown to the user on mobile devices | | `invalid` | `boolean` | No | Whether the number input value is invalid. | | `locale` | `string` | No | The current locale. Based on the BCP 47 definition. | | `max` | `number` | No | The maximum value of the number input | | `min` | `number` | No | The minimum value of the number input | | `name` | `string` | No | The name attribute of the number input. Useful for form submission. | | `onFocusChange` | `(details: FocusChangeDetails) => void` | No | Function invoked when the number input is focused | | `onValueChange` | `(details: ValueChangeDetails) => void` | No | Function invoked when the value changes | | `onValueInvalid` | `(details: ValueInvalidDetails) => void` | No | Function invoked when the value overflows or underflows the min/max range | | `pattern` | `string` | No | The pattern used to check the element's value against | | `readOnly` | `boolean` | No | Whether the number input is readonly | | `required` | `boolean` | No | Whether the number input is required | | `spinOnPress` | `boolean` | No | Whether to spin the value when the increment/decrement button is pressed | | `step` | `number` | No | The amount to increment or decrement the value by | | `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states | | `value` | `string` | No | The controlled value of the input | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | root | | `[data-disabled]` | Present when disabled | | `[data-focus]` | Present when focused | | `[data-invalid]` | Present when invalid | | `[data-scrubbing]` | | **Control 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. | **Control Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | control | | `[data-focus]` | Present when focused | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-scrubbing]` | | **DecrementTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **DecrementTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | decrement-trigger | | `[data-disabled]` | Present when disabled | | `[data-scrubbing]` | | **IncrementTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **IncrementTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | increment-trigger | | `[data-disabled]` | Present when disabled | | `[data-scrubbing]` | | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'input'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | input | | `[data-invalid]` | Present when invalid | | `[data-disabled]` | Present when disabled | | `[data-scrubbing]` | | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'label'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | label | | `[data-disabled]` | Present when disabled | | `[data-focus]` | Present when focused | | `[data-invalid]` | Present when invalid | | `[data-required]` | Present when required | | `[data-scrubbing]` | | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseNumberInputReturn` | Yes | | | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Scrubber 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. | **Scrubber Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | scrubber | | `[data-disabled]` | Present when disabled | | `[data-scrubbing]` | | **ValueText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'span'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ValueText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | value-text | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-focus]` | Present when focused | | `[data-scrubbing]` | | #### Vue **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `allowMouseWheel` | `boolean` | No | Whether to allow mouse wheel to change the value | | `allowOverflow` | `boolean` | No | Whether to allow the value overflow the min/max range | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `clampValueOnBlur` | `boolean` | No | Whether to clamp the value when the input loses focus (blur) | | `defaultValue` | `string` | No | The initial value of the input when rendered. Use when you don't need to control the value of the input. | | `disabled` | `boolean` | No | Whether the number input is disabled. | | `focusInputOnChange` | `boolean` | No | Whether to focus input when the value changes | | `form` | `string` | No | The associate form of the input element. | | `formatOptions` | `NumberFormatOptions` | No | The options to pass to the `Intl.NumberFormat` constructor | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string label: string input: string incrementTrigger: string decrementTrigger: string scrubber: string }>` | No | The ids of the elements in the number input. Useful for composition. | | `inputMode` | `'text' | 'tel' | 'numeric' | 'decimal'` | No | Hints at the type of data that might be entered by the user. It also determines the type of keyboard shown to the user on mobile devices | | `invalid` | `boolean` | No | Whether the number input value is invalid. | | `locale` | `string` | No | The current locale. Based on the BCP 47 definition. | | `max` | `number` | No | The maximum value of the number input | | `min` | `number` | No | The minimum value of the number input | | `modelValue` | `string` | No | The v-model value of the number input | | `name` | `string` | No | The name attribute of the number input. Useful for form submission. | | `pattern` | `string` | No | The pattern used to check the element's value against | | `readOnly` | `boolean` | No | Whether the number input is readonly | | `required` | `boolean` | No | Whether the number input is required | | `spinOnPress` | `boolean` | No | Whether to spin the value when the increment/decrement button is pressed | | `step` | `number` | No | The amount to increment or decrement the value by | | `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | root | | `[data-disabled]` | Present when disabled | | `[data-focus]` | Present when focused | | `[data-invalid]` | Present when invalid | | `[data-scrubbing]` | | **Control Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Control Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | control | | `[data-focus]` | Present when focused | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-scrubbing]` | | **DecrementTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **DecrementTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | decrement-trigger | | `[data-disabled]` | Present when disabled | | `[data-scrubbing]` | | **IncrementTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **IncrementTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | increment-trigger | | `[data-disabled]` | Present when disabled | | `[data-scrubbing]` | | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | input | | `[data-invalid]` | Present when invalid | | `[data-disabled]` | Present when disabled | | `[data-scrubbing]` | | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | label | | `[data-disabled]` | Present when disabled | | `[data-focus]` | Present when focused | | `[data-invalid]` | Present when invalid | | `[data-required]` | Present when required | | `[data-scrubbing]` | | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `NumberInputApi{(context) => } ` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Scrubber Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Scrubber Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | scrubber | | `[data-disabled]` | Present when disabled | | `[data-scrubbing]` | | **ValueText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ValueText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | value-text | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-focus]` | Present when focused | | `[data-scrubbing]` | | #### Svelte **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `allowMouseWheel` | `boolean` | No | Whether to allow mouse wheel to change the value | | `allowOverflow` | `boolean` | No | Whether to allow the value overflow the min/max range | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `clampValueOnBlur` | `boolean` | No | Whether to clamp the value when the input loses focus (blur) | | `defaultValue` | `string` | No | The initial value of the input when rendered. Use when you don't need to control the value of the input. | | `disabled` | `boolean` | No | Whether the number input is disabled. | | `focusInputOnChange` | `boolean` | No | Whether to focus input when the value changes | | `form` | `string` | No | The associate form of the input element. | | `formatOptions` | `NumberFormatOptions` | No | The options to pass to the `Intl.NumberFormat` constructor | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string label: string input: string incrementTrigger: string decrementTrigger: string scrubber: string }>` | No | The ids of the elements in the number input. Useful for composition. | | `inputMode` | `InputMode` | No | Hints at the type of data that might be entered by the user. It also determines the type of keyboard shown to the user on mobile devices | | `invalid` | `boolean` | No | Whether the number input value is invalid. | | `locale` | `string` | No | The current locale. Based on the BCP 47 definition. | | `max` | `number` | No | The maximum value of the number input | | `min` | `number` | No | The minimum value of the number input | | `name` | `string` | No | The name attribute of the number input. Useful for form submission. | | `onFocusChange` | `(details: FocusChangeDetails) => void` | No | Function invoked when the number input is focused | | `onValueChange` | `(details: ValueChangeDetails) => void` | No | Function invoked when the value changes | | `onValueInvalid` | `(details: ValueInvalidDetails) => void` | No | Function invoked when the value overflows or underflows the min/max range | | `pattern` | `string` | No | The pattern used to check the element's value against | | `readOnly` | `boolean` | No | Whether the number input is readonly | | `ref` | `Element` | No | | | `required` | `boolean` | No | Whether the number input is required | | `spinOnPress` | `boolean` | No | Whether to spin the value when the increment/decrement button is pressed | | `step` | `number` | No | The amount to increment or decrement the value by | | `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states | | `value` | `string` | No | The controlled value of the input | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | root | | `[data-disabled]` | Present when disabled | | `[data-focus]` | Present when focused | | `[data-invalid]` | Present when invalid | | `[data-scrubbing]` | | **Context Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `render` | `Snippet<[UseNumberInputContext]>` | Yes | | **Control 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. | | `ref` | `Element` | No | | **Control Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | control | | `[data-focus]` | Present when focused | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-scrubbing]` | | **DecrementTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **DecrementTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | decrement-trigger | | `[data-disabled]` | Present when disabled | | `[data-scrubbing]` | | **IncrementTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **IncrementTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | increment-trigger | | `[data-disabled]` | Present when disabled | | `[data-scrubbing]` | | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'input'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Input Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | input | | `[data-invalid]` | Present when invalid | | `[data-disabled]` | Present when disabled | | `[data-scrubbing]` | | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'label'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | label | | `[data-disabled]` | Present when disabled | | `[data-focus]` | Present when focused | | `[data-invalid]` | Present when invalid | | `[data-required]` | Present when required | | `[data-scrubbing]` | | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseNumberInputReturn` | Yes | | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Scrubber Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Scrubber Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | scrubber | | `[data-disabled]` | Present when disabled | | `[data-scrubbing]` | | **ValueText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **ValueText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | number-input | | `[data-part]` | value-text | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-focus]` | Present when focused | | `[data-scrubbing]` | | ### Context These are the properties available when using `NumberInput.Context`, `useNumberInputContext` hook or `useNumberInput` hook. **API:** | Property | Type | Description | |----------|------|-------------| | `focused` | `boolean` | Whether the input is focused. | | `invalid` | `boolean` | Whether the input is invalid. | | `empty` | `boolean` | Whether the input value is empty. | | `value` | `string` | The formatted value of the input. | | `valueAsNumber` | `number` | The value of the input as a number. | | `setValue` | `(value: number) => void` | Function to set the value of the input. | | `clearValue` | `VoidFunction` | Function to clear the value of the input. | | `increment` | `VoidFunction` | Function to increment the value of the input by the step. | | `decrement` | `VoidFunction` | Function to decrement the value of the input by the step. | | `setToMax` | `VoidFunction` | Function to set the value of the input to the max. | | `setToMin` | `VoidFunction` | Function to set the value of the input to the min. | | `focus` | `VoidFunction` | Function to focus the input. | ## Accessibility Complies with the [Spinbutton WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/). ### Keyboard Support **`ArrowUp`** Description: Increments the value of the number input by a predefined step. **`ArrowDown`** Description: Decrements the value of the number input by a predefined step. **`PageUp`** Description: Increments the value of the number input by a larger predefined step. **`PageDown`** Description: Decrements the value of the number input by a larger predefined step. **`Home`** Description: Sets the value of the number input to its minimum allowed value. **`End`** Description: Sets the value of the number input to its maximum allowed value. **`Enter`** Description: Submits the value entered in the number input. # Pagination ## Anatomy To set up the pagination correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples Learn how to use the `Pagination` component in your project. Let's take a look at the most basic example: **Example: basic** #### React ```tsx import { Pagination } from '@ark-ui/react/pagination' export const Basic = () => ( Previous Page {(pagination) => pagination.pages.map((page, index) => page.type === 'page' ? ( {page.value} ) : (… ), ) }Next Page Previous Page {(api) => ( {(page, index) => page.type === 'page' ? ( )}{page.value} ) : (… ) }Next Page Previous Page {{ page.value }} … Next Page Previous Page {#snippet render(pagination)} {#each pagination().pages as page, index (index)} {#if page.type === 'page'} {page.value} {:else}… {/if} {/each} {/snippet}Next Page setCurrentPage(details.page)} > ) } ``` #### Solid ```tsx import { Pagination } from '@ark-ui/solid/pagination' import { For, createSignal } from 'solid-js' export const Controlled = () => { const [currentPage, setCurrentPage] = createSignal(1) return (Previous {(pagination) => pagination.pages.map((page, index) => page.type === 'page' ? ( {page.value} ) : (… ), ) }Next Page setCurrentPage(details.page)} > ) } ``` #### Vue ```vuePrevious Page {(api) => ( {(page, index) => page.type === 'page' ? ( )}{page.value} ) : (… ) }Next Page Previous Page {{ page.value }} … Next Page Previous {#snippet render(pagination)} {#each pagination().pages as page, index (index)} {#if page.type === 'page'} {page.value} {:else}… {/if} {/each} {/snippet}Next Page `Page ${details.page}`, }} > ) ``` #### Solid ```tsx import { Pagination } from '@ark-ui/solid/pagination' import { For } from 'solid-js' export const Customized = () => { return (Previous {(pagination) => pagination.pages.map((page, index) => page.type === 'page' ? ( {page.value} ) : (… ), ) }Next Page `Page ${details.page}`, }} > ) } ``` #### Vue ```vuePrevious Page {(api) => ( {(page, index) => page.type === 'page' ? ( )}{page.value} ) : (… ) }Next Page Previous Page {{ page.value }} … Next Page `Page ${details.page}`, }} > ``` ### Using Context The `Context` component provides access to the pagination state and methods through a render prop pattern. This allows you to access methods like `setPage`, `setPageSize`, `goToNextPage`, `goToPrevPage`, `goToFirstPage`, `goToLastPage`, as well as properties like `totalPages` and `pageRange`. **Example: context** #### React ```tsx import { Pagination } from '@ark-ui/react/pagination' export const Context = () => { return (Previous {#snippet render(pagination)} {#each pagination().pages as page, index (index)} {#if page.type === 'page'} {page.value} {:else}… {/if} {/each} {/snippet}Next Page {(pagination) => ( )}Page {pagination.page} of {pagination.totalPages}
Items {pagination.pageRange.start + 1}-{pagination.pageRange.end}
{(api) => ( )}Page {api().page} of {api().totalPages}
Items {api().pageRange.start + 1}-{api().pageRange.end}
Page {{ pagination.page }} of {{ pagination.totalPages }}
Items {{ pagination.pageRange.start + 1 }}-{{ pagination.pageRange.end }}
{#snippet render(pagination)} {/snippet}Page {pagination().page} of {pagination().totalPages}
Items {pagination().pageRange.start + 1}-{pagination().pageRange.end}
{(pagination) => ( )}Current Page Items:
-
{pagination.slice(items).map((item) => (
- {item} ))}
Previous {pagination.pages.map((page, index) => page.type === 'page' ? ({page.value} ) : (… ), )}Next {(api) => ( )}Current Page Items:
- {item} }
{(item) => Previous {(page, index) => page.type === 'page' ? ( {page.value} ) : (… ) }Next Current Page Items:
- {{ item }}
Previous {{ page.value }} … Next {#snippet render(pagination)} {/snippet}Current Page Items:
-
{#each pagination().slice(items) as item}
- {item} {/each}
Previous {#each pagination().pages as page, index} {#if page.type === 'page'}{page.value} {:else}… {/if} {/each}Next {(pagination) => ( )}Previous {pagination.pages.map((page, index) => page.type === 'page' ? ({page.value} ) : (… ), )}Next Showing {pagination.pageRange.start + 1}-{pagination.pageRange.end} of {pagination.count} results
Page {pagination.page} of {pagination.totalPages}
{(api) => ( )}Previous {(page, index) => page.type === 'page' ? ( {page.value} ) : (… ) }Next Showing {api().pageRange.start + 1}-{api().pageRange.end} of {api().count} results
Page {api().page} of {api().totalPages}
Previous {{ page.value }} … Next Showing {{ pagination.pageRange.start + 1 }}-{{ pagination.pageRange.end }} of {{ pagination.count }} results
Page {{ pagination.page }} of {{ pagination.totalPages }}
{#snippet render(pagination)} {/snippet}Previous {#each pagination().pages as page, index} {#if page.type === 'page'}{page.value} {:else}… {/if} {/each}Next Showing {pagination().pageRange.start + 1}-{pagination().pageRange.end} of {pagination().count} results
Page {pagination().page} of {pagination().totalPages}
{(pagination) => ( )}Previous {pagination.pages.map((page, index) => page.type === 'page' ? ({page.value} ) : (… ), )}Next Page {pagination.page} of {pagination.totalPages}
{(api) => ( )}Previous {(page, index) => page.type === 'page' ? ( {page.value} ) : (… ) }Next Page {api().page} of {api().totalPages}
Previous {{ page.value }} … Next Page {{ pagination.page }} of {{ pagination.totalPages }}
{#snippet render(pagination)} {/snippet}Previous {#each pagination().pages as page, index} {#if page.type === 'page'}{page.value} {:else}… {/if} {/each}Next Page {pagination().page} of {pagination().totalPages}
Previous {pagination.pages.map((page, index) => page.type === 'page' ? ( {page.value} ) : ( … ), )} Next ) } ``` #### Solid ```tsx import { Pagination, usePagination } from '@ark-ui/solid/pagination' import { For } from 'solid-js' export const Link = () => { const pagination = usePagination({ type: 'link', count: 100, pageSize: 10, siblingCount: 2, getPageUrl: ({ page }) => `/page=${page}`, }) return (Previous ) } ``` #### Vue ```vue{(page, index) => page.type === 'page' ? ( {page.value} ) : ( … ) } NextPrevious {{ page.value }} … Next ``` #### Svelte ```sveltePrevious {#each pagination().pages as page, index (index)} {#if page.type === 'page'} {page.value} {:else} … {/if} {/each} Next ``` ### Root Provider The `RootProvider` component provides a context for the pagination. It accepts the value of the `usePagination` hook. You can leverage it to access the component state and methods from outside the pagination. **Example: root-provider** #### React ```tsx import { Pagination, usePagination } from '@ark-ui/react/pagination' export const RootProvider = () => { const pagination = usePagination({ count: 5000, pageSize: 10, siblingCount: 2 }) return ( <>Previous Page {(pagination) => pagination.pages.map((page, index) => page.type === 'page' ? ( {page.value} ) : (… ), ) }Next Page Previous Page {(api) => ( {(page, index) => page.type === 'page' ? ( )}{page.value} ) : (… ) }Next Page Previous Page {{ page.value }} … Next Page Previous Page {#each pagination().pages as page, index (index)} {#if page.type === 'page'}{page.value} {:else}… {/if} {/each}Next Page ` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | #### Svelte **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'nav'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `count` | `number` | No | Total number of data items | | `defaultPage` | `number` | No | The initial active page when rendered. Use when you don't need to control the active page of the pagination. | | `defaultPageSize` | `number` | No | The initial number of data items per page when rendered. Use when you don't need to control the page size of the pagination. | | `getPageUrl` | `(details: PageUrlDetails) => string` | No | Function to generate href attributes for pagination links. Only used when `type` is set to "link". | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string ellipsis: (index: number) => string prevTrigger: string nextTrigger: string item: (page: number) => string }>` | No | The ids of the elements in the accordion. Useful for composition. | | `onPageChange` | `(details: PageChangeDetails) => void` | No | Called when the page number is changed | | `onPageSizeChange` | `(details: PageSizeChangeDetails) => void` | No | Called when the page size is changed | | `page` | `number` | No | The controlled active page | | `pageSize` | `number` | No | The controlled number of data items per page | | `ref` | `Element` | No | | | `siblingCount` | `number` | No | Number of pages to show beside active page | | `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states | | `type` | `'button' | 'link'` | No | The type of the trigger element | **Context Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `render` | `Snippet<[UsePaginationContext]>` | Yes | | **Ellipsis Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `index` | `number` | Yes | | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Item Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `type` | `'page'` | Yes | | | `value` | `number` | Yes | | | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | pagination | | `[data-part]` | item | | `[data-index]` | The index of the item | | `[data-selected]` | Present when selected | **NextTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **NextTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | pagination | | `[data-part]` | next-trigger | | `[data-disabled]` | Present when disabled | **PrevTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **PrevTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | pagination | | `[data-part]` | prev-trigger | | `[data-disabled]` | Present when disabled | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UsePaginationReturn` | Yes | | | `asChild` | `Snippet<[PropsFn<'nav'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | ### Context These are the properties available when using `Pagination.Context`, `usePaginationContext` hook or `usePagination` hook. **API:** | Property | Type | Description | |----------|------|-------------| | `page` | `number` | The current page. | | `count` | `number` | The total number of data items. | | `pageSize` | `number` | The number of data items per page. | | `totalPages` | `number` | The total number of pages. | | `pages` | `Pages` | The page range. Represented as an array of page numbers (including ellipsis) | | `previousPage` | `number` | The previous page. | | `nextPage` | `number` | The next page. | | `pageRange` | `PageRange` | The page range. Represented as an object with `start` and `end` properties. | | `slice` | ` (data: V[]) => V[]` | Function to slice an array of data based on the current page. | | `setPageSize` | `(size: number) => void` | Function to set the page size. | | `setPage` | `(page: number) => void` | Function to set the current page. | | `goToNextPage` | `VoidFunction` | Function to go to the next page. | | `goToPrevPage` | `VoidFunction` | Function to go to the previous page. | | `goToFirstPage` | `VoidFunction` | Function to go to the first page. | | `goToLastPage` | `VoidFunction` | Function to go to the last page. | # Password Input ## Anatomy To set up the password input correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples Learn how to use the `PasswordInput` component in your project. Let's take a look at the most basic example: **Example: basic** #### React ```tsx import { PasswordInput } from '@ark-ui/react/password-input' import { EyeIcon, EyeOffIcon } from 'lucide-react' export const Basic = () => ( Password }> Password }> Password Password {#snippet fallback()} {/snippet} Password }> Password }> Password Current Password {#snippet fallback()} {/snippet} Password }> Password }> Password ``` ### Field Here's an example of how to use the `PasswordInput` component with the `Field` component. **Example: with-field** #### React ```tsx import { Field } from '@ark-ui/react/field' import { PasswordInput } from '@ark-ui/react/password-input' import { EyeIcon, EyeOffIcon } from 'lucide-react' export const WithField = () => (Password (with external control) {#snippet fallback()} {/snippet} Password }> Enter your password Password is required Password }> Enter your password Password is required Password Your password must be at least 8 characters Password is required Password {#snippet fallback()} {/snippet} Enter your password Password is required API Key }> API Key }> API Key Password (no password manager) {#snippet fallback()} {/snippet} setVisible(e.visible)}> ) } ``` #### Solid ```tsx import { PasswordInput } from '@ark-ui/solid/password-input' import { EyeIcon, EyeOffIcon } from 'lucide-solid' import { createSignal } from 'solid-js' export const ControlledVisibility = () => { const [visible, setVisible] = createSignal(false) return (Password is {visible ? 'visible' : 'hidden'} }> setVisible(e.visible)}> ) } ``` #### Vue ```vuePassword is {visible() ? 'visible' : 'hidden'} }> Password is {{ visible ? 'visible' : 'hidden' }} ``` ### Strength meter Combine the `PasswordInput` with a password strength library to show visual feedback about password strength. This example uses the [`check-password-strength`](https://www.npmjs.com/package/check-password-strength) package to provide real-time strength validation. **Example: strength-meter** #### React ```tsx import { PasswordInput } from '@ark-ui/react/password-input' import { passwordStrength, type Options } from 'check-password-strength' import { EyeIcon, EyeOffIcon } from 'lucide-react' import { useMemo, useState } from 'react' const strengthOptions: Options{JSON.stringify({ visible }, null, 2)}Password (controlled) {#snippet fallback()} {/snippet} = [ { id: 0, value: 'weak', minDiversity: 0, minLength: 0 }, { id: 1, value: 'medium', minDiversity: 2, minLength: 6 }, { id: 2, value: 'strong', minDiversity: 4, minLength: 8 }, ] const strengthMap = new Map([ ['weak', { color: 'red', width: '30%' }], ['medium', { color: 'orange', width: '60%' }], ['strong', { color: 'green', width: '100%' }], ]) export const StrengthMeter = () => { const [password, setPassword] = useState('') const strength = useMemo(() => { if (!password) return null const { value } = passwordStrength(password, strengthOptions) const data = strengthMap.get(value) return data ? { value, ...data } : null }, [password]) return ( Password setPassword(e.currentTarget.value)} placeholder="Enter your password" /> }> )}{strength.value} password= [ { id: 0, value: 'weak', minDiversity: 0, minLength: 0 }, { id: 1, value: 'medium', minDiversity: 2, minLength: 6 }, { id: 2, value: 'strong', minDiversity: 4, minLength: 8 }, ] const strengthMap = new Map([ ['weak', { color: 'red', width: '30%' }], ['medium', { color: 'orange', width: '60%' }], ['strong', { color: 'green', width: '100%' }], ]) export const StrengthMeter = () => { const [password, setPassword] = createSignal('') const strength = createMemo(() => { if (!password()) return null const { value } = passwordStrength(password(), strengthOptions) const data = strengthMap.get(value) return data ? { value, ...data } : null }) return ( Password setPassword(e.currentTarget.value)} placeholder="Enter your password" /> }> {(value) => ( )}{value().value} passwordPassword {{ strength.value }} passwordPassword {#snippet fallback()} {/snippet} {/if}{strength.value} password| ReactPortal | Promise<...>` | No | The fallback content to display when the password is not visible. | **Indicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | password-input | | `[data-part]` | indicator | | `[data-state]` | "visible" | "hidden" | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | password-input | | `[data-part]` | input | | `[data-state]` | "visible" | "hidden" | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | password-input | | `[data-part]` | label | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | | `[data-required]` | Present when required | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UsePasswordInputReturn` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **VisibilityTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **VisibilityTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | password-input | | `[data-part]` | visibility-trigger | | `[data-readonly]` | Present when read-only | | `[data-disabled]` | Present when disabled | | `[data-state]` | "visible" | "hidden" | #### Solid **Root 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. | | `autoComplete` | `'current-password' | 'new-password'` | No | The autocomplete attribute for the password input. | | `defaultVisible` | `boolean` | No | The default visibility of the password input. | | `disabled` | `boolean` | No | Whether the password input is disabled. | | `ids` | `Partial<{ input: string; visibilityTrigger: string }>` | No | The ids of the password input parts | | `ignorePasswordManagers` | `boolean` | No | When `true`, the input will ignore password managers. **Only works for the following password managers** - 1Password, LastPass, Bitwarden, Dashlane, Proton Pass | | `invalid` | `boolean` | No | The invalid state of the password input. | | `name` | `string` | No | The name of the password input. | | `onVisibilityChange` | `(details: VisibilityChangeDetails) => void` | No | Function called when the visibility changes. | | `readOnly` | `boolean` | No | Whether the password input is read only. | | `required` | `boolean` | No | Whether the password input is required. | | `translations` | `Partial<{ visibilityTrigger: ((visible: boolean) => string) | undefined }>` | No | The localized messages to use. | | `visible` | `boolean` | No | Whether the password input is visible. | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | password-input | | `[data-part]` | root | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **Control 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. | **Control Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | password-input | | `[data-part]` | control | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **Indicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'span'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `fallback` | `number | boolean | Node | ArrayElement | (string & {})` | No | The fallback content to display when the password is not visible. | **Indicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | password-input | | `[data-part]` | indicator | | `[data-state]` | "visible" | "hidden" | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'input'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | password-input | | `[data-part]` | input | | `[data-state]` | "visible" | "hidden" | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'label'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | password-input | | `[data-part]` | label | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | | `[data-required]` | Present when required | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UsePasswordInputContext` | Yes | | | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **VisibilityTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **VisibilityTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | password-input | | `[data-part]` | visibility-trigger | | `[data-readonly]` | Present when read-only | | `[data-disabled]` | Present when disabled | | `[data-state]` | "visible" | "hidden" | #### Vue **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `autoComplete` | `'current-password' | 'new-password'` | No | The autocomplete attribute for the input | | `defaultVisible` | `boolean` | No | Whether the password is visible by default | | `disabled` | `boolean` | No | Whether the input is disabled | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ input: string; visibilityTrigger: string }>` | No | The ids of the elements in the password input. Useful for composition. | | `ignorePasswordManagers` | `boolean` | No | Whether to ignore password managers | | `invalid` | `boolean` | No | Whether the input is in an invalid state | | `name` | `string` | No | The name attribute for the input | | `readOnly` | `boolean` | No | Whether the input is read-only | | `required` | `boolean` | No | Whether the input is required | | `translations` | `Partial<{ visibilityTrigger: ((visible: boolean) => string) | undefined }>` | No | Specifies the localized strings that identifies the accessibility elements and their states | | `visible` | `boolean` | No | Whether the password is visible | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | password-input | | `[data-part]` | root | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **Context Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UsePasswordInputReturn` | Yes | | **Control Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Control Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | password-input | | `[data-part]` | control | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **Indicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `fallback` | `string` | No | The fallback content to display when the password is not visible. | **Indicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | password-input | | `[data-part]` | indicator | | `[data-state]` | "visible" | "hidden" | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | password-input | | `[data-part]` | input | | `[data-state]` | "visible" | "hidden" | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | password-input | | `[data-part]` | label | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | | `[data-required]` | Present when required | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `PasswordInputApi ` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **VisibilityTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **VisibilityTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | password-input | | `[data-part]` | visibility-trigger | | `[data-readonly]` | Present when read-only | | `[data-disabled]` | Present when disabled | | `[data-state]` | "visible" | "hidden" | #### Svelte **Root 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. | | `autoComplete` | `'current-password' | 'new-password'` | No | The autocomplete attribute for the password input. | | `defaultVisible` | `boolean` | No | The default visibility of the password input. | | `disabled` | `boolean` | No | Whether the password input is disabled. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ input: string; visibilityTrigger: string }>` | No | The ids of the password input parts | | `ignorePasswordManagers` | `boolean` | No | When `true`, the input will ignore password managers. **Only works for the following password managers** - 1Password, LastPass, Bitwarden, Dashlane, Proton Pass | | `invalid` | `boolean` | No | The invalid state of the password input. | | `name` | `string` | No | The name of the password input. | | `onVisibilityChange` | `(details: VisibilityChangeDetails) => void` | No | Function called when the visibility changes. | | `readOnly` | `boolean` | No | Whether the password input is read only. | | `ref` | `Element` | No | | | `required` | `boolean` | No | Whether the password input is required. | | `translations` | `Partial<{ visibilityTrigger: ((visible: boolean) => string) | undefined }>` | No | The localized messages to use. | | `visible` | `boolean` | No | Whether the password input is visible. | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | password-input | | `[data-part]` | root | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **Context Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `render` | `Snippet<[UsePasswordInputContext]>` | No | | **Control 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. | | `ref` | `Element` | No | | **Control Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | password-input | | `[data-part]` | control | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **Indicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `fallback` | `Snippet<[]>` | No | The fallback content to display when the password is not visible. | | `ref` | `Element` | No | | **Indicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | password-input | | `[data-part]` | indicator | | `[data-state]` | "visible" | "hidden" | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'input'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Input Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | password-input | | `[data-part]` | input | | `[data-state]` | "visible" | "hidden" | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'label'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | password-input | | `[data-part]` | label | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | | `[data-required]` | Present when required | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UsePasswordInputReturn` | Yes | | | `ref` | `Element` | No | | **VisibilityTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **VisibilityTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | password-input | | `[data-part]` | visibility-trigger | | `[data-readonly]` | Present when read-only | | `[data-disabled]` | Present when disabled | | `[data-state]` | "visible" | "hidden" | ### Context These are the properties available when using `PasswordInput.Context`, `usePasswordInputContext` hook or `usePasswordInput` hook. **API:** | Property | Type | Description | |----------|------|-------------| | `visible` | `boolean` | Whether the password input is visible. | | `disabled` | `boolean` | Whether the password input is disabled. | | `invalid` | `boolean` | Whether the password input is invalid. | | `focus` | `VoidFunction` | Focus the password input. | | `setVisible` | `(value: boolean) => void` | Set the visibility of the password input. | | `toggleVisible` | `VoidFunction` | Toggle the visibility of the password input. | # Pin Input ## Anatomy To set up the pin input correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples Learn how to use the `PinInput` component in your project. Let's take a look at the most basic example: **Example: basic** #### React ```tsx import { PinInput } from '@ark-ui/react/pin-input' export const Basic = () => ( alert(e.valueAsString)}> ) ``` #### Solid ```tsx import { PinInput } from '@ark-ui/solid/pin-input' import { Index } from 'solid-js' export const Basic = () => (Label {[0, 1, 2].map((id, index) => ( ))} alert(e.valueAsString)}> ) ``` #### Vue ```vueLabel {(id) => } Label alert(details.valueAsString)}> ``` ### Setting a default value To set the initial value of the pin input, set the `defaultValue` prop. **Example: initial-value** #### React ```tsx import { PinInput } from '@ark-ui/react/pin-input' export const InitialValue = () => (Label {#each [0, 1, 2] as index} {/each} Label {[0, 1, 2].map((id, index) => ( ))} Label {(id) => } Label Enter your PIN (default: 123) {#each [0, 1, 2] as index} {/each} Label {[0, 1, 2].map((id, index) => ( ))} Label {(id) => } Label ``` ### Blur on complete By default, the last input maintains focus when filled, and we invoke the `onValueComplete` callback. To blur the last input when the user completes the input, set the prop `blurOnComplete` to `true`. **Example: blurred** #### React ```tsx import { PinInput } from '@ark-ui/react/pin-input' export const Blurred = () => ({JSON.stringify({ value }, null, 2)}Enter PIN {#each [0, 1, 2, 3] as index} {/each} Label {[0, 1, 2].map((id, index) => ( ))} Label {(id) => } Label PIN (blurs on complete) {#each [0, 1, 2] as index} {/each} Label {[0, 1, 2].map((id, index) => ( ))} Label {(id) => } Label Enter verification code {#each [0, 1, 2, 3, 4, 5] as index} {/each} Label {[0, 1, 2].map((id, index) => ( ))} Label {(id) => } Label Enter your secure PIN {#each [0, 1, 2, 3] as index} {/each} Label {[0, 1, 2].map((id, index) => ( ))} Additional Info Error Info Label {(id) => } Additional Info Error Info Label Additional Info Error Info Label {#each [0, 1, 2] as id, index (id)} {/each} Additional Info Error Info Label {[0, 1, 2].map((id, index) => ( ))} Label {(id) => } Label ``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference ### Props **Component API Reference** #### React **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `autoFocus` | `boolean` | No | Whether to auto-focus the first input. | | `blurOnComplete` | `boolean` | No | Whether to blur the input when the value is complete | | `count` | `number` | No | The number of inputs to render to improve SSR aria attributes. This will be required in next major version. | | `defaultValue` | `string[]` | No | The initial value of the the pin input when rendered. Use when you don't need to control the value of the pin input. | | `disabled` | `boolean` | No | Whether the inputs are disabled | | `form` | `string` | No | The associate form of the underlying input element. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string hiddenInput: string label: string control: string input: (id: string) => string }>` | No | The ids of the elements in the pin input. Useful for composition. | | `invalid` | `boolean` | No | Whether the pin input is in the invalid state | | `mask` | `boolean` | No | If `true`, the input's value will be masked just like `type=password` | | `name` | `string` | No | The name of the input element. Useful for form submission. | | `onValueChange` | `(details: ValueChangeDetails) => void` | No | Function called on input change | | `onValueComplete` | `(details: ValueChangeDetails) => void` | No | Function called when all inputs have valid values | | `onValueInvalid` | `(details: ValueInvalidDetails) => void` | No | Function called when an invalid value is entered | | `otp` | `boolean` | No | If `true`, the pin input component signals to its fields that they should use `autocomplete="one-time-code"`. | | `pattern` | `string` | No | The regular expression that the user-entered input value is checked against. | | `placeholder` | `string` | No | The placeholder text for the input | | `readOnly` | `boolean` | No | Whether the pin input is in the valid state | | `required` | `boolean` | No | Whether the pin input is required | | `selectOnFocus` | `boolean` | No | Whether to select input value when input is focused | | `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states | | `type` | `'numeric' | 'alphanumeric' | 'alphabetic'` | No | The type of value the pin-input should allow | | `value` | `string[]` | No | The controlled value of the the pin input. | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | pin-input | | `[data-part]` | root | | `[data-invalid]` | Present when invalid | | `[data-disabled]` | Present when disabled | | `[data-complete]` | Present when the pin-input value is complete | | `[data-readonly]` | Present when read-only | **Control Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **HiddenInput Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `index` | `number` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | pin-input | | `[data-part]` | input | | `[data-disabled]` | Present when disabled | | `[data-complete]` | Present when the input value is complete | | `[data-index]` | The index of the item | | `[data-invalid]` | Present when invalid | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | pin-input | | `[data-part]` | label | | `[data-invalid]` | Present when invalid | | `[data-disabled]` | Present when disabled | | `[data-complete]` | Present when the label value is complete | | `[data-required]` | Present when required | | `[data-readonly]` | Present when read-only | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UsePinInputReturn` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | #### Solid **Root 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. | | `autoFocus` | `boolean` | No | Whether to auto-focus the first input. | | `blurOnComplete` | `boolean` | No | Whether to blur the input when the value is complete | | `count` | `number` | No | The number of inputs to render to improve SSR aria attributes. This will be required in next major version. | | `defaultValue` | `string[]` | No | The initial value of the the pin input when rendered. Use when you don't need to control the value of the pin input. | | `disabled` | `boolean` | No | Whether the inputs are disabled | | `form` | `string` | No | The associate form of the underlying input element. | | `ids` | `Partial<{ root: string hiddenInput: string label: string control: string input: (id: string) => string }>` | No | The ids of the elements in the pin input. Useful for composition. | | `invalid` | `boolean` | No | Whether the pin input is in the invalid state | | `mask` | `boolean` | No | If `true`, the input's value will be masked just like `type=password` | | `name` | `string` | No | The name of the input element. Useful for form submission. | | `onValueChange` | `(details: ValueChangeDetails) => void` | No | Function called on input change | | `onValueComplete` | `(details: ValueChangeDetails) => void` | No | Function called when all inputs have valid values | | `onValueInvalid` | `(details: ValueInvalidDetails) => void` | No | Function called when an invalid value is entered | | `otp` | `boolean` | No | If `true`, the pin input component signals to its fields that they should use `autocomplete="one-time-code"`. | | `pattern` | `string` | No | The regular expression that the user-entered input value is checked against. | | `placeholder` | `string` | No | The placeholder text for the input | | `readOnly` | `boolean` | No | Whether the pin input is in the valid state | | `required` | `boolean` | No | Whether the pin input is required | | `selectOnFocus` | `boolean` | No | Whether to select input value when input is focused | | `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states | | `type` | `'numeric' | 'alphanumeric' | 'alphabetic'` | No | The type of value the pin-input should allow | | `value` | `string[]` | No | The controlled value of the the pin input. | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | pin-input | | `[data-part]` | root | | `[data-invalid]` | Present when invalid | | `[data-disabled]` | Present when disabled | | `[data-complete]` | Present when the pin-input value is complete | | `[data-readonly]` | Present when read-only | **Control 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. | **HiddenInput Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'input'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `index` | `number` | Yes | | | `asChild` | `(props: ParentProps<'input'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | pin-input | | `[data-part]` | input | | `[data-disabled]` | Present when disabled | | `[data-complete]` | Present when the input value is complete | | `[data-index]` | The index of the item | | `[data-invalid]` | Present when invalid | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'label'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | pin-input | | `[data-part]` | label | | `[data-invalid]` | Present when invalid | | `[data-disabled]` | Present when disabled | | `[data-complete]` | Present when the label value is complete | | `[data-required]` | Present when required | | `[data-readonly]` | Present when read-only | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UsePinInputReturn` | Yes | | | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | #### Vue **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `autoFocus` | `boolean` | No | Whether to auto-focus the first input. | | `blurOnComplete` | `boolean` | No | Whether to blur the input when the value is complete | | `count` | `number` | No | The number of inputs to render to improve SSR aria attributes. This will be required in next major version. | | `defaultValue` | `string[]` | No | The initial value of the the pin input when rendered. Use when you don't need to control the value of the pin input. | | `disabled` | `boolean` | No | Whether the inputs are disabled | | `form` | `string` | No | The associate form of the underlying input element. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string hiddenInput: string label: string control: string input(id: string): string }>` | No | The ids of the elements in the pin input. Useful for composition. | | `invalid` | `boolean` | No | Whether the pin input is in the invalid state | | `mask` | `boolean` | No | If `true`, the input's value will be masked just like `type=password` | | `modelValue` | `string[]` | No | The v-model value of the pin input | | `name` | `string` | No | The name of the input element. Useful for form submission. | | `otp` | `boolean` | No | If `true`, the pin input component signals to its fields that they should use `autocomplete="one-time-code"`. | | `pattern` | `string` | No | The regular expression that the user-entered input value is checked against. | | `placeholder` | `string` | No | The placeholder text for the input | | `readOnly` | `boolean` | No | Whether the pin input is in the valid state | | `required` | `boolean` | No | Whether the pin input is required | | `selectOnFocus` | `boolean` | No | Whether to select input value when input is focused | | `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states | | `type` | `'numeric' | 'alphanumeric' | 'alphabetic'` | No | The type of value the pin-input should allow | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | pin-input | | `[data-part]` | root | | `[data-invalid]` | Present when invalid | | `[data-disabled]` | Present when disabled | | `[data-complete]` | Present when the pin-input value is complete | | `[data-readonly]` | Present when read-only | **Control Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **HiddenInput Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `index` | `number` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | pin-input | | `[data-part]` | input | | `[data-disabled]` | Present when disabled | | `[data-complete]` | Present when the input value is complete | | `[data-index]` | The index of the item | | `[data-invalid]` | Present when invalid | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | pin-input | | `[data-part]` | label | | `[data-invalid]` | Present when invalid | | `[data-disabled]` | Present when disabled | | `[data-complete]` | Present when the label value is complete | | `[data-required]` | Present when required | | `[data-readonly]` | Present when read-only | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `PinInputApiPIN (with external control) {#each [0, 1, 2] as index} {/each} ` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | #### Svelte **Root 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. | | `autoFocus` | `boolean` | No | Whether to auto-focus the first input. | | `blurOnComplete` | `boolean` | No | Whether to blur the input when the value is complete | | `count` | `number` | No | The number of inputs to render to improve SSR aria attributes. This will be required in next major version. | | `defaultValue` | `string[]` | No | The initial value of the the pin input when rendered. Use when you don't need to control the value of the pin input. | | `disabled` | `boolean` | No | Whether the inputs are disabled | | `form` | `string` | No | The associate form of the underlying input element. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string hiddenInput: string label: string control: string input: (id: string) => string }>` | No | The ids of the elements in the pin input. Useful for composition. | | `invalid` | `boolean` | No | Whether the pin input is in the invalid state | | `mask` | `boolean` | No | If `true`, the input's value will be masked just like `type=password` | | `name` | `string` | No | The name of the input element. Useful for form submission. | | `onValueChange` | `(details: ValueChangeDetails) => void` | No | Function called on input change | | `onValueComplete` | `(details: ValueChangeDetails) => void` | No | Function called when all inputs have valid values | | `onValueInvalid` | `(details: ValueInvalidDetails) => void` | No | Function called when an invalid value is entered | | `otp` | `boolean` | No | If `true`, the pin input component signals to its fields that they should use `autocomplete="one-time-code"`. | | `pattern` | `string` | No | The regular expression that the user-entered input value is checked against. | | `placeholder` | `string` | No | The placeholder text for the input | | `readOnly` | `boolean` | No | Whether the pin input is in the valid state | | `ref` | `Element` | No | | | `required` | `boolean` | No | Whether the pin input is required | | `selectOnFocus` | `boolean` | No | Whether to select input value when input is focused | | `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states | | `type` | `'numeric' | 'alphanumeric' | 'alphabetic'` | No | The type of value the pin-input should allow | | `value` | `string[]` | No | The controlled value of the the pin input. | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | pin-input | | `[data-part]` | root | | `[data-invalid]` | Present when invalid | | `[data-disabled]` | Present when disabled | | `[data-complete]` | Present when the pin-input value is complete | | `[data-readonly]` | Present when read-only | **Context Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `render` | `Snippet<[UsePinInputContext]>` | No | | **Control 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. | | `ref` | `Element` | No | | **HiddenInput Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'input'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `index` | `number` | Yes | | | `asChild` | `Snippet<[PropsFn<'input'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Input Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | pin-input | | `[data-part]` | input | | `[data-disabled]` | Present when disabled | | `[data-complete]` | Present when the input value is complete | | `[data-index]` | The index of the item | | `[data-invalid]` | Present when invalid | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'label'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | pin-input | | `[data-part]` | label | | `[data-invalid]` | Present when invalid | | `[data-disabled]` | Present when disabled | | `[data-complete]` | Present when the label value is complete | | `[data-required]` | Present when required | | `[data-readonly]` | Present when read-only | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UsePinInputReturn` | Yes | | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | ### Context These are the properties available when using `UpinUinput.Context`, `useUpinUinputContext` hook or `useUpinUinput` hook. **API:** | Property | Type | Description | |----------|------|-------------| | `value` | `string[]` | The value of the input as an array of strings. | | `valueAsString` | `string` | The value of the input as a string. | | `complete` | `boolean` | Whether all inputs are filled. | | `count` | `number` | The number of inputs to render | | `items` | `number[]` | The array of input values. | | `setValue` | `(value: string[]) => void` | Function to set the value of the inputs. | | `clearValue` | `VoidFunction` | Function to clear the value of the inputs. | | `setValueAtIndex` | `(index: number, value: string) => void` | Function to set the value of the input at a specific index. | | `focus` | `VoidFunction` | Function to focus the pin-input. This will focus the first input. | ## Accessibility ### Keyboard Support **`ArrowLeft`** Description: Moves focus to the previous input **`ArrowRight`** Description: Moves focus to the next input **`Backspace`** Description: Deletes the value in the current input and moves focus to the previous input **`Delete`** Description: Deletes the value in the current input **`Control + V`** Description: Pastes the value into the input fields # Popover ## Anatomy To set up the popover correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples Learn how to use the `Popover` component in your project. Let's take a look at the most basic example: **Example: basic** #### React ```tsx import { Popover } from '@ark-ui/react/popover' import { ChevronRightIcon } from 'lucide-react' export const Basic = () => ( Click Me Title Description Click Me Title Description Click Me {{ '>' }} Title Description Click Me Title Description Click Me Title Description Click Me Title Description Click Me {{ '>' }} Title Description Click Me Title Description Click Me Title Description Close Click Me Title Description Close Click Me Title Description Close Click Me Title Description alert(open ? 'opened' : 'closed')}> ) } ``` #### Solid ```tsx import { Popover } from '@ark-ui/solid/popover' import { ChevronRightIcon } from 'lucide-solid' export const OnOpenChange = () => { return (Click Me Title Description alert(open ? 'opened' : 'closed')}> ) } ``` #### Vue ```vueClick Me Title Description Click Me {{ '>' }} Title Description alert(open ? 'opened' : 'closed')}> ``` ### Control the open state Use the `isOpen` prop to control the open state of the popover. **Example: controlled** #### React ```tsx import { Popover } from '@ark-ui/react/popover' import { useState } from 'react' export const Controlled = () => { const [isOpen, setIsOpen] = useState(false) return ( <>Click Me Title Description Anchor Title Description Close Anchor Title Description Close Anchor Title Description Close Anchor Title Description Close Click Me Title Description Close Click Me Title Description Close Click Me Title Description Close Click Me Title Description Close Click Me Title Description Close Click Me Title Description Close Click Me Title Description Close Click Me Title Description Close Click Me Title Description Close Click Me Title Description Close Click Me Title Description Close Click Me Title Description Close Title Description Click Me Title Description Click Me {{ '>' }} Title Description Title Description ; /* width of the available viewport */ --available-width: ; /* height of the available viewport */ --available-height: ; ``` For example, if you want to make sure the maximum height doesn't exceed the available height, use the following css: ```css [data-scope='popover'][data-part='content'] { max-height: calc(var(--available-height) - 100px); } ``` ## API Reference ### Props **Component API Reference** #### React **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `autoFocus` | `boolean` | No | Whether to automatically set focus on the first focusable content within the popover when opened. | | `closeOnEscape` | `boolean` | No | Whether to close the popover when the escape key is pressed. | | `closeOnInteractOutside` | `boolean` | No | Whether to close the popover when the user clicks outside of the popover. | | `defaultOpen` | `boolean` | No | The initial open state of the popover when rendered. Use when you don't need to control the open state of the popover. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ anchor: string trigger: string content: string title: string description: string closeTrigger: string positioner: string arrow: string }>` | No | The ids of the elements in the popover. Useful for composition. | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `initialFocusEl` | `() => HTMLElement | null` | No | The element to focus on when the popover is opened. | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `modal` | `boolean` | No | Whether the popover should be modal. When set to `true`: - interaction with outside elements will be disabled - only popover content will be visible to screen readers - scrolling is blocked - focus is trapped within the popover | | `onEscapeKeyDown` | `(event: KeyboardEvent) => void` | No | Function called when the escape key is pressed | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component | | `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component | | `onOpenChange` | `(details: OpenChangeDetails) => void` | No | Function invoked when the popover opens or closes | | `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component | | `onRequestDismiss` | `(event: LayerDismissEvent) => void` | No | Function called when this layer is closed due to a parent layer being closed | | `open` | `boolean` | No | The controlled open state of the popover | | `persistentElements` | `(() => Element | null)[]` | No | Returns the persistent elements that: - should not have pointer-events disabled - should not trigger the dismiss event | | `portalled` | `boolean` | No | Whether the popover is portalled. This will proxy the tabbing behavior regardless of the DOM position of the popover content. | | `positioning` | `PositioningOptions` | No | The user provided options used to position the popover content | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Anchor Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Arrow Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ArrowTip Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **CloseTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Content Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Content Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | popover | | `[data-part]` | content | | `[data-state]` | "open" | "closed" | | `[data-nested]` | popover | | `[data-has-nested]` | popover | | `[data-expanded]` | Present when expanded | | `[data-placement]` | The placement of the content | **Description Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Indicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Indicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | popover | | `[data-part]` | indicator | | `[data-state]` | "open" | "closed" | **Positioner Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UsePopoverReturn` | Yes | | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Title Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | popover | | `[data-part]` | trigger | | `[data-placement]` | The placement of the trigger | | `[data-state]` | "open" | "closed" | #### Solid **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `autoFocus` | `boolean` | No | Whether to automatically set focus on the first focusable content within the popover when opened. | | `closeOnEscape` | `boolean` | No | Whether to close the popover when the escape key is pressed. | | `closeOnInteractOutside` | `boolean` | No | Whether to close the popover when the user clicks outside of the popover. | | `defaultOpen` | `boolean` | No | The initial open state of the popover when rendered. Use when you don't need to control the open state of the popover. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ anchor: string trigger: string content: string title: string description: string closeTrigger: string positioner: string arrow: string }>` | No | The ids of the elements in the popover. Useful for composition. | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `initialFocusEl` | `() => HTMLElement | null` | No | The element to focus on when the popover is opened. | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `modal` | `boolean` | No | Whether the popover should be modal. When set to `true`: - interaction with outside elements will be disabled - only popover content will be visible to screen readers - scrolling is blocked - focus is trapped within the popover | | `onEscapeKeyDown` | `(event: KeyboardEvent) => void` | No | Function called when the escape key is pressed | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component | | `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component | | `onOpenChange` | `(details: OpenChangeDetails) => void` | No | Function invoked when the popover opens or closes | | `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component | | `onRequestDismiss` | `(event: LayerDismissEvent) => void` | No | Function called when this layer is closed due to a parent layer being closed | | `open` | `boolean` | No | The controlled open state of the popover | | `persistentElements` | `(() => Element | null)[]` | No | Returns the persistent elements that: - should not have pointer-events disabled - should not trigger the dismiss event | | `portalled` | `boolean` | No | Whether the popover is portalled. This will proxy the tabbing behavior regardless of the DOM position of the popover content. | | `positioning` | `PositioningOptions` | No | The user provided options used to position the popover content | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Anchor 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. | **Arrow 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. | **ArrowTip 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. | **CloseTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Content 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. | **Content Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | popover | | `[data-part]` | content | | `[data-state]` | "open" | "closed" | | `[data-nested]` | popover | | `[data-has-nested]` | popover | | `[data-expanded]` | Present when expanded | | `[data-placement]` | The placement of the content | **Description 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. | **Indicator 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. | **Indicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | popover | | `[data-part]` | indicator | | `[data-state]` | "open" | "closed" | **Positioner 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. | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UsePopoverReturn` | Yes | | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Title 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. | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | popover | | `[data-part]` | trigger | | `[data-placement]` | The placement of the trigger | | `[data-state]` | "open" | "closed" | #### Vue **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `autoFocus` | `boolean` | No | Whether to automatically set focus on the first focusable content within the popover when opened. | | `closeOnEscape` | `boolean` | No | Whether to close the popover when the escape key is pressed. | | `closeOnInteractOutside` | `boolean` | No | Whether to close the popover when the user clicks outside of the popover. | | `defaultOpen` | `boolean` | No | The initial open state of the popover when rendered. Use when you don't need to control the open state of the popover. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ anchor: string trigger: string content: string title: string description: string closeTrigger: string positioner: string arrow: string }>` | No | The ids of the elements in the popover. Useful for composition. | | `initialFocusEl` | `() => HTMLElement | null` | No | The element to focus on when the popover is opened. | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `modal` | `boolean` | No | Whether the popover should be modal. When set to `true`: - interaction with outside elements will be disabled - only popover content will be visible to screen readers - scrolling is blocked - focus is trapped within the popover | | `open` | `boolean` | No | The controlled open state of the popover | | `persistentElements` | `(() => Element | null)[]` | No | Returns the persistent elements that: - should not have pointer-events disabled - should not trigger the dismiss event | | `portalled` | `boolean` | No | Whether the popover is portalled. This will proxy the tabbing behavior regardless of the DOM position of the popover content. | | `positioning` | `PositioningOptions` | No | The user provided options used to position the popover content | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Anchor Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Arrow Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ArrowTip Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **CloseTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Content Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Content Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | popover | | `[data-part]` | content | | `[data-state]` | "open" | "closed" | | `[data-nested]` | popover | | `[data-has-nested]` | popover | | `[data-expanded]` | Present when expanded | | `[data-placement]` | The placement of the content | **Description Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Indicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Indicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | popover | | `[data-part]` | indicator | | `[data-state]` | "open" | "closed" | **Positioner Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `PopoverApi ` | Yes | | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Title Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | popover | | `[data-part]` | trigger | | `[data-placement]` | The placement of the trigger | | `[data-state]` | "open" | "closed" | #### Svelte **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `autoFocus` | `boolean` | No | Whether to automatically set focus on the first focusable content within the popover when opened. | | `closeOnEscape` | `boolean` | No | Whether to close the popover when the escape key is pressed. | | `closeOnInteractOutside` | `boolean` | No | Whether to close the popover when the user clicks outside of the popover. | | `defaultOpen` | `boolean` | No | The initial open state of the popover when rendered. Use when you don't need to control the open state of the popover. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ anchor: string trigger: string content: string title: string description: string closeTrigger: string positioner: string arrow: string }>` | No | The ids of the elements in the popover. Useful for composition. | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `initialFocusEl` | `() => HTMLElement | null` | No | The element to focus on when the popover is opened. | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `modal` | `boolean` | No | Whether the popover should be modal. When set to `true`: - interaction with outside elements will be disabled - only popover content will be visible to screen readers - scrolling is blocked - focus is trapped within the popover | | `onEscapeKeyDown` | `(event: KeyboardEvent) => void` | No | Function called when the escape key is pressed | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component | | `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component | | `onOpenChange` | `(details: OpenChangeDetails) => void` | No | Function invoked when the popover opens or closes | | `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component | | `onRequestDismiss` | `(event: LayerDismissEvent) => void` | No | Function called when this layer is closed due to a parent layer being closed | | `open` | `boolean` | No | The controlled open state of the popover | | `persistentElements` | `(() => Element | null)[]` | No | Returns the persistent elements that: - should not have pointer-events disabled - should not trigger the dismiss event | | `portalled` | `boolean` | No | Whether the popover is portalled. This will proxy the tabbing behavior regardless of the DOM position of the popover content. | | `positioning` | `PositioningOptions` | No | The user provided options used to position the popover content | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Anchor 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. | | `ref` | `Element` | No | | **Arrow 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. | | `ref` | `Element` | No | | **ArrowTip 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. | | `ref` | `Element` | No | | **CloseTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Content 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. | | `ref` | `Element` | No | | **Content Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | popover | | `[data-part]` | content | | `[data-state]` | "open" | "closed" | | `[data-nested]` | popover | | `[data-has-nested]` | popover | | `[data-expanded]` | Present when expanded | | `[data-placement]` | The placement of the content | **Context Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `render` | `Snippet<[UsePopoverContext]>` | No | | **Description Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'p'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Indicator 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. | | `ref` | `Element` | No | | **Indicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | popover | | `[data-part]` | indicator | | `[data-state]` | "open" | "closed" | **Positioner 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. | | `ref` | `Element` | No | | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UsePopoverReturn` | Yes | | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Title Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'h2'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | popover | | `[data-part]` | trigger | | `[data-placement]` | The placement of the trigger | | `[data-state]` | "open" | "closed" | ### Context These are the properties available when using `Popover.Context`, `usePopoverContext` hook or `usePopover` hook. **API:** | Property | Type | Description | |----------|------|-------------| | `portalled` | `boolean` | Whether the popover is portalled. | | `open` | `boolean` | Whether the popover is open | | `setOpen` | `(open: boolean) => void` | Function to open or close the popover | | `reposition` | `(options?: Partial ) => void` | Function to reposition the popover | ## Accessibility ### Keyboard Support **`Space`** Description: Opens/closes the popover. **`Enter`** Description: Opens/closes the popover. **`Tab`** Description: Moves focus to the next focusable element within the content.
Note: If there are no focusable elements, focus is moved to the next focusable element after the trigger. **`Shift + Tab`** Description: Moves focus to the previous focusable element within the content
Note: If there are no focusable elements, focus is moved to the trigger. **`Esc`** Description: Closes the popover and moves focus to the trigger. # Progress - Circular ## Anatomy To set up the progress correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples Learn how to use the `Progress` component in your project. Let's take a look at the most basic example: **Example: basic** #### React ```tsx import { Progress } from '@ark-ui/react/progress' export const Basic = () => (Label Label Label Label Label Label Label Label Label Label Label Label Label Label Label (value == null ? 'Loading...' : `${value} of ${max} items loaded`), }} > ``` ### Using the Root Provider The `RootProvider` component provides a context for the progress. It accepts the value of the `useProgress` hook. You can leverage it to access the component state and methods from outside the progress. **Example: root-provider** #### React ```tsx import { Progress, useProgress } from '@ark-ui/react/progress' export const RootProvider = () => { const progress = useProgress() return ( <>Label Label Label Label Label ` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Track Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ValueText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **View Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `state` | `ProgressState` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **View Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | progress | | `[data-part]` | view | | `[data-state]` | | #### Svelte **Root 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. | | `defaultValue` | `number` | No | The initial value of the progress bar when rendered. Use when you don't need to control the value of the progress bar. | | `formatOptions` | `NumberFormatOptions` | No | The options to use for formatting the value. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string; track: string; label: string; circle: string }>` | No | The ids of the elements in the progress bar. Useful for composition. | | `locale` | `string` | No | The locale to use for formatting the value. | | `max` | `number` | No | The maximum allowed value of the progress bar. | | `min` | `number` | No | The minimum allowed value of the progress bar. | | `onValueChange` | `(details: ValueChangeDetails) => void` | No | Callback fired when the value changes. | | `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the element. | | `ref` | `Element` | No | | | `translations` | `IntlTranslations` | No | The localized messages to use. | | `value` | `number` | No | The controlled value of the progress bar. | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | progress | | `[data-part]` | root | | `[data-max]` | | | `[data-value]` | The value of the item | | `[data-state]` | | | `[data-orientation]` | The orientation of the progress | **Circle Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'svg'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **CircleRange Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'circle'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **CircleRange Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | progress | | `[data-part]` | circle-range | | `[data-state]` | | **CircleTrack Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'circle'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **CircleTrack Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | progress | | `[data-part]` | circle-track | | `[data-orientation]` | The orientation of the circletrack | **Context Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `api` | `Snippet<[UseProgressContext]>` | No | | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'label'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | progress | | `[data-part]` | label | | `[data-orientation]` | The orientation of the label | **Range 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. | | `ref` | `Element` | No | | **Range Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | progress | | `[data-part]` | range | | `[data-orientation]` | The orientation of the range | | `[data-state]` | | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseProgressReturn` | Yes | | | `ref` | `Element` | No | | **Track 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. | | `ref` | `Element` | No | | **ValueText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **View Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `state` | `ProgressState` | Yes | | | `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **View Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | progress | | `[data-part]` | view | | `[data-state]` | | ## Accessibility Complies with the [the progressbar role requirements.](https://w3c.github.io/aria/#progressbar). # Progress - Linear ## Anatomy To set up the progress correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples Learn how to use the `Progress` component in your project. Let's take a look at the most basic example: **Example: basic** #### React ```tsx import { Progress } from '@ark-ui/react/progress' export const Basic = () => ( Label Label Label Label Label Label Label Label Label Label Label Label Label Label Label (value == null ? 'Loading...' : `${value} of ${max} items loaded`), }} > ``` ### Changing the orientation By default, the progress is assumed to be horizontal. To change the orientation to vertical, set the orientation property in the machine's context to vertical. > Don't forget to change the styles of the vertical progress by specifying its height **Example: vertical** #### React ```tsx import { Progress } from '@ark-ui/react/progress' export const Vertical = () => (Label Label Label Label Label Label Label Label Label ` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Track Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ValueText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **View Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `state` | `ProgressState` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **View Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | progress | | `[data-part]` | view | | `[data-state]` | | #### Svelte **Root 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. | | `defaultValue` | `number` | No | The initial value of the progress bar when rendered. Use when you don't need to control the value of the progress bar. | | `formatOptions` | `NumberFormatOptions` | No | The options to use for formatting the value. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string; track: string; label: string; circle: string }>` | No | The ids of the elements in the progress bar. Useful for composition. | | `locale` | `string` | No | The locale to use for formatting the value. | | `max` | `number` | No | The maximum allowed value of the progress bar. | | `min` | `number` | No | The minimum allowed value of the progress bar. | | `onValueChange` | `(details: ValueChangeDetails) => void` | No | Callback fired when the value changes. | | `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the element. | | `ref` | `Element` | No | | | `translations` | `IntlTranslations` | No | The localized messages to use. | | `value` | `number` | No | The controlled value of the progress bar. | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | progress | | `[data-part]` | root | | `[data-max]` | | | `[data-value]` | The value of the item | | `[data-state]` | | | `[data-orientation]` | The orientation of the progress | **Circle Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'svg'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **CircleRange Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'circle'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **CircleRange Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | progress | | `[data-part]` | circle-range | | `[data-state]` | | **CircleTrack Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'circle'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **CircleTrack Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | progress | | `[data-part]` | circle-track | | `[data-orientation]` | The orientation of the circletrack | **Context Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `api` | `Snippet<[UseProgressContext]>` | No | | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'label'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | progress | | `[data-part]` | label | | `[data-orientation]` | The orientation of the label | **Range 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. | | `ref` | `Element` | No | | **Range Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | progress | | `[data-part]` | range | | `[data-orientation]` | The orientation of the range | | `[data-state]` | | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseProgressReturn` | Yes | | | `ref` | `Element` | No | | **Track 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. | | `ref` | `Element` | No | | **ValueText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **View Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `state` | `ProgressState` | Yes | | | `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **View Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | progress | | `[data-part]` | view | | `[data-state]` | | ## Accessibility Complies with the [the progressbar role requirements.](https://w3c.github.io/aria/#progressbar). # QR Code ## Anatomy To set up the QR code correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples Learn how to use the `QR Code` component in your project. Let's take a look at the most basic example: **Example: basic** #### React ```tsx import { QrCode } from '@ark-ui/react/qr-code' export const Basic = () => { return ( Download Download Download Download 
Download ``` ## API Reference ### Props **Component API Reference** #### React **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `defaultValue` | `string` | No | The initial value to encode when rendered. Use when you don't need to control the value of the qr code. | | `encoding` | `QrCodeGenerateOptions` | No | The qr code encoding options. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string; frame: string }>` | No | The element ids. | | `onValueChange` | `(details: ValueChangeDetails) => void` | No | Callback fired when the value changes. | | `pixelSize` | `number` | No | The pixel size of the qr code. | | `value` | `string` | No | The controlled value to encode. | **DownloadTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `fileName` | `string` | Yes | The name of the file. | | `mimeType` | `DataUrlType` | Yes | The mime type of the image. | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `quality` | `number` | No | The quality of the image. | **Frame Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Overlay Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Pattern Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseQrCodeReturn` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | #### Solid **Root 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. | | `defaultValue` | `string` | No | The initial value to encode when rendered. Use when you don't need to control the value of the qr code. | | `encoding` | `QrCodeGenerateOptions` | No | The qr code encoding options. | | `ids` | `Partial<{ root: string; frame: string }>` | No | The element ids. | | `onValueChange` | `(details: ValueChangeDetails) => void` | No | Callback fired when the value changes. | | `pixelSize` | `number` | No | The pixel size of the qr code. | | `value` | `string` | No | The controlled value to encode. | **DownloadTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `fileName` | `string` | Yes | The name of the file. | | `mimeType` | `DataUrlType` | Yes | The mime type of the image. | | `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `quality` | `number` | No | The quality of the image. | **Frame Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'svg'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Overlay 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. | **Pattern Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'path'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseQrCodeReturn` | Yes | | | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | #### Vue **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `defaultValue` | `string` | No | The initial value to encode when rendered. Use when you don't need to control the value of the qr code. | | `encoding` | `QrCodeGenerateOptions` | No | The qr code encoding options. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string; frame: string }>` | No | The element ids. | | `modelValue` | `string` | No | The v-model value of the qr code | | `pixelSize` | `number` | No | The pixel size of the qr code. | **DownloadTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `fileName` | `string` | Yes | The name of the file. | | `mimeType` | `DataUrlType` | Yes | The mime type of the image. | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `quality` | `number` | No | The quality of the image. | **Frame Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Overlay Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Pattern Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `QrCodeApi` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | #### Svelte **Root 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. | | `defaultValue` | `string` | No | The initial value to encode when rendered. Use when you don't need to control the value of the qr code. | | `encoding` | `QrCodeGenerateOptions` | No | The qr code encoding options. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string; frame: string }>` | No | The element ids. | | `onValueChange` | `(details: ValueChangeDetails) => void` | No | Callback fired when the value changes. | | `pixelSize` | `number` | No | The pixel size of the qr code. | | `ref` | `Element` | No | | | `value` | `string` | No | The controlled value to encode. | **Context Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `api` | `Snippet<[UseQrCodeContext]>` | No | | **DownloadTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `fileName` | `string` | Yes | The name of the file. | | `mimeType` | `DataUrlType` | Yes | The mime type of the image. | | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `quality` | `number` | No | The quality of the image. | | `ref` | `Element` | No | | **Frame Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'svg'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Overlay 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. | | `ref` | `Element` | No | | **Pattern Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'path'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseQrCodeReturn` | Yes | | | `ref` | `Element` | No | | ### Context These are the properties available when using `UqrUcode.Context`, `useUqrUcodeContext` hook or `useUqrUcode` hook. **API:** | Property | Type | Description | |----------|------|-------------| | `value` | `string` | The value to encode. | | `setValue` | `(value: string) => void` | Set the value to encode. | | `getDataUrl` | `(type: DataUrlType, quality?: number) => Promise ` | Returns the data URL of the qr code. | # Radio Group ## Anatomy To set up the radio group correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples Learn how to use the `RadioGroup` component in your project. Let's take a look at the most basic example: **Example: basic** #### React ```tsx import { RadioGroup } from '@ark-ui/react/radio-group' export const Basic = () => { const frameworks = ['React', 'Solid', 'Vue', 'Svelte'] return ( Framework {frameworks.map((framework) => ( {framework} Framework {(framework) => ( {framework()} Framework {{ framework }} Framework {#each frameworks as framework} {framework} Framework {frameworks.map((framework) => ({framework} Framework {(framework) => ( {framework()} Framework {{ framework }} Framework {#each frameworks as framework}{framework} Framework {frameworks.map((framework) => ({framework} Framework {(framework) => ( {framework()} Framework {{ framework }} Framework {#each frameworks as framework}{framework} console.log(details.value)}> ) } ``` #### Solid ```tsx import { RadioGroup } from '@ark-ui/solid/radio-group' import { Index } from 'solid-js' export const OnEvent = () => { const frameworks = ['React', 'Solid', 'Vue', 'Svelte'] return (Framework {frameworks.map((framework) => ({framework} console.log(details.value)}> ) } ``` #### Vue ```vueFramework {(framework) => ( {framework()} Framework {{ framework }} console.log(details.value)}> ``` ### Using the Root Provider The `RootProvider` component provides a context for the radio-group. It accepts the value of the `useRadio-group` hook. You can leverage it to access the component state and methods from outside the radio-group. **Example: root-provider** #### React ```tsx import { RadioGroup, useRadioGroup } from '@ark-ui/react/radio-group' export const RootProvider = () => { const frameworks = ['React', 'Solid', 'Vue', 'Svelte'] const radioGroup = useRadioGroup() return ( <>Framework {#each frameworks as framework}{framework} Framework {frameworks.map((framework) => ( {framework} Framework {(framework) => ( {framework()} Framework {{ framework }} Framework {#each frameworks as framework} {framework} ` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | #### Svelte **Root 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. | | `defaultValue` | `string` | No | The initial value of the checked radio when rendered. Use when you don't need to control the value of the radio group. | | `disabled` | `boolean` | No | If `true`, the radio group will be disabled | | `form` | `string` | No | The associate form of the underlying input. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string label: string indicator: string item: (value: string) => string itemLabel: (value: string) => string itemControl: (value: string) => string itemHiddenInput: (value: string) => string }>` | No | The ids of the elements in the radio. Useful for composition. | | `name` | `string` | No | The name of the input fields in the radio (Useful for form submission). | | `onValueChange` | `(details: ValueChangeDetails) => void` | No | Function called once a radio is checked | | `orientation` | `'horizontal' | 'vertical'` | No | Orientation of the radio group | | `readOnly` | `boolean` | No | Whether the checkbox is read-only | | `ref` | `Element` | No | | | `value` | `string` | No | The controlled value of the radio group | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | radio-group | | `[data-part]` | root | | `[data-orientation]` | The orientation of the radio-group | | `[data-disabled]` | Present when disabled | **Indicator 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. | | `ref` | `Element` | No | | **Indicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | radio-group | | `[data-part]` | indicator | | `[data-disabled]` | Present when disabled | | `[data-orientation]` | The orientation of the indicator | **ItemContext Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `render` | `Snippet<[UseRadioGroupItemContext]>` | Yes | | **ItemControl 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. | | `ref` | `Element` | No | | **ItemControl Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | radio-group | | `[data-part]` | item-control | | `[data-active]` | Present when active or pressed | **ItemHiddenInput Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'input'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Item Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `string` | Yes | | | `asChild` | `Snippet<[PropsFn<'label'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `disabled` | `boolean` | No | | | `invalid` | `boolean` | No | | | `ref` | `Element` | No | | **ItemText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'label'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | radio-group | | `[data-part]` | label | | `[data-orientation]` | The orientation of the label | | `[data-disabled]` | Present when disabled | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseRadioGroupReturn` | Yes | | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | ### Context These are the properties available when using `RadioGroup.Context`, `useRadioGroupContext` hook or `useRadioGroup` hook. **API:** | Property | Type | Description | |----------|------|-------------| | `value` | `string` | The current value of the radio group | | `setValue` | `(value: string) => void` | Function to set the value of the radio group | | `clearValue` | `VoidFunction` | Function to clear the value of the radio group | | `focus` | `VoidFunction` | Function to focus the radio group | | `getItemState` | `(props: ItemProps) => ItemState` | Returns the state details of a radio input | ## Accessibility Complies with the [Radio WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/). ### Keyboard Support **`Tab`** Description: Moves focus to either the checked radio item or the first radio item in the group. **`Space`** Description: When focus is on an unchecked radio item, checks it. **`ArrowDown`** Description: Moves focus and checks the next radio item in the group. **`ArrowRight`** Description: Moves focus and checks the next radio item in the group. **`ArrowUp`** Description: Moves focus to the previous radio item in the group. **`ArrowLeft`** Description: Moves focus to the previous radio item in the group. # Rating Group ## Anatomy To set up the rating correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples Learn how to use the `RatingGroup` component in your project. Let's take a look at the most basic example: **Example: basic** #### React ```tsx import { RatingGroup } from '@ark-ui/react/rating-group' import { StarIcon } from 'lucide-react' export const Basic = () => ( Label {({ items }) => items.map((item) => ( {({ highlighted }) => (highlighted ? : )} Label {(context) => ( {(index) => ( )}{(context) => ( }> )} Label Label {#snippet render(ratingGroup)} {#each ratingGroup().items as item} {#snippet render(itemState)} {#if itemState().highlighted} {:else} {/if} {/snippet} Label {({ items }) => items.map((item) => ( {({ half, highlighted }) => { if (half) return if (highlighted) return return }} Label {(context) => ( {(index) => ( )}{(context) => context().half ? ( ) : context().highlighted ? ( ) : ( ) } Label Label {#snippet render(ratingGroup)} {#each ratingGroup().items as item (item)} {#snippet render(itemState)} {#if itemState().half} {:else if itemState().highlighted} {:else} {/if} {/snippet} Label {({ items }) => items.map((item) => ( {({ highlighted }) => (highlighted ? : )} Label {(context) => ( {(index) => ( )}{(context) => ( }> )} Label Label {#snippet render(ratingGroup)} {#each ratingGroup().items as item (item)} {#snippet render(itemState)} {#if itemState().highlighted} {:else} {/if} {/snippet} setValue(details.value)} allowHalf> ) } ``` #### Solid ```tsx import { RatingGroup } from '@ark-ui/solid/rating-group' import { StarIcon } from 'lucide-solid' import { Index, Show, createSignal } from 'solid-js' export const Controlled = () => { const [value, setValue] = createSignal(0) return (Label {({ items }) => items.map((item) => ( {({ highlighted }) => (highlighted ? : )} setValue(details.value)}> ) } ``` #### Vue ```vueLabel {(context) => ( {(index) => ( )}{(context) => ( }> )} Label {{ value }} Label {#snippet render(ratingGroup)} {#each ratingGroup().items as item} {#snippet render(itemState)} {#if itemState().highlighted} {:else} {/if} {/snippet} Label {({ items }) => items.map((item) => ( {({ highlighted }) => (highlighted ? : )} Label {(context) => ( {(index) => ( )}{(context) => ( }> )} Label Label {#snippet render(ratingGroup)} {#each ratingGroup().items as item} {#snippet render(itemState)} {#if itemState().highlighted} {:else} {/if} {/snippet} Label {({ items }) => items.map((item) => ( {({ highlighted }) => (highlighted ? : )} Label {(context) => ( {(index) => ( )}{(context) => ( }> )} Label Label {#snippet render(ratingGroup)} {#each ratingGroup().items as item} {#snippet render(itemState)} {#if itemState().highlighted} {:else} {/if} {/snippet} Label {({ items }) => items.map((item) => ( {({ highlighted }) => (highlighted ? : )} Label {(context) => ( {(index) => ( )}{(context) => ( }> )} Label Label {#snippet render(ratingGroup)} {#each ratingGroup().items as item (item)} {#snippet render(itemState)} {#if itemState().highlighted} {:else} {/if} {/snippet} Label {({ items }) => items.map((item) => ( {({ highlighted }) => (highlighted ? : )} Additional Info Error Info Label {(context) => ( {(index) => ( )}{(context) => ( }> )} Additional Info Error Info Label Additional Info Error Info Label {#snippet render(ratingGroup)} {#each ratingGroup().items as item} {#snippet render(itemState)} {#if itemState().highlighted} {:else} {/if} {/snippet} Additional Info Error Info Label {({ items }) => items.map((item) => ( {({ highlighted }) => (highlighted ? : )} Label {(context) => ( {(index) => ( )}{(context) => ( }> )} Label Label {#snippet render(ratingGroup)} {#each ratingGroup().items as item} {#snippet render(itemState)} {#if itemState().highlighted} {:else} {/if} {/snippet} ` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | #### Svelte **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `allowHalf` | `boolean` | No | Whether to allow half stars. | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `autoFocus` | `boolean` | No | Whether to autofocus the rating. | | `count` | `number` | No | The total number of ratings. | | `defaultValue` | `number` | No | The initial value of the rating when rendered. Use when you don't need to control the value of the rating. | | `disabled` | `boolean` | No | Whether the rating is disabled. | | `form` | `string` | No | The associate form of the underlying input element. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string label: string hiddenInput: string control: string item: (id: string) => string }>` | No | The ids of the elements in the rating. Useful for composition. | | `name` | `string` | No | The name attribute of the rating element (used in forms). | | `onHoverChange` | `(details: HoverChangeDetails) => void` | No | Function to be called when the rating value is hovered. | | `onValueChange` | `(details: ValueChangeDetails) => void` | No | Function to be called when the rating value changes. | | `readOnly` | `boolean` | No | Whether the rating is readonly. | | `ref` | `Element` | No | | | `required` | `boolean` | No | Whether the rating is required. | | `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states | | `value` | `number` | No | The controlled value of the rating | **Context Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `render` | `Snippet<[UseRatingGroupContext]>` | Yes | | **Control 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. | | `ref` | `Element` | No | | **Control Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | rating-group | | `[data-part]` | control | | `[data-readonly]` | Present when read-only | | `[data-disabled]` | Present when disabled | **HiddenInput Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'input'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **ItemContext Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `render` | `Snippet<[UseRatingGroupItemContext]>` | Yes | | **Item Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `index` | `number` | Yes | | | `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | rating-group | | `[data-part]` | item | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | | `[data-checked]` | Present when checked | | `[data-highlighted]` | Present when highlighted | | `[data-half]` | | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'label'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | rating-group | | `[data-part]` | label | | `[data-disabled]` | Present when disabled | | `[data-required]` | Present when required | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseRatingGroupReturn` | Yes | | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | ### Context These are the properties available when using `RatingGroup.Context`, `useRatingGroupContext` hook or `useRatingGroup` hook. **API:** | Property | Type | Description | |----------|------|-------------| | `setValue` | `(value: number) => void` | Sets the value of the rating group | | `clearValue` | `VoidFunction` | Clears the value of the rating group | | `hovering` | `boolean` | Whether the rating group is being hovered | | `value` | `number` | The current value of the rating group | | `hoveredValue` | `number` | The value of the currently hovered rating | | `count` | `number` | The total number of ratings | | `items` | `number[]` | The array of rating values. Returns an array of numbers from 1 to the max value. | | `getItemState` | `(props: ItemProps) => ItemState` | Returns the state of a rating item | ## Accessibility ### Keyboard Support **`ArrowRight`** Description: Moves focus to the next star, increasing the rating value based on the `allowHalf` property. **`ArrowLeft`** Description: Moves focus to the previous star, decreasing the rating value based on the `allowHalf` property. **`Enter`** Description: Selects the focused star in the rating group. # Scroll Area ## Features - Cross-browser custom scrollbars - Native scroll behavior - Keyboard navigation support - Touch and mouse support - Horizontal and vertical scrolling - Support for nested scroll areas - Customizable scrollbar appearance ## Anatomy To set up the scroll area correctly, it's essential to understand its anatomy and the naming of its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Required style It's important to note that the scroll area requires the following styles on the `ScrollArea.Viewport` element to hide the native scrollbar: ```css [data-scope='scroll-area'][data-part='viewport'] { scrollbar-width: none; &::-webkit-scrollbar { display: none; } } ``` ## Examples ### Basic Usage Create a basic scrollable area with custom scrollbar. **Example: basic** #### React ```tsx import { ScrollArea } from '@ark-ui/react/scroll-area' export const Basic = () => ( Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem.
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt.
At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis praesentium voluptatum deleniti atque corrupti quos dolores et quas molestias excepturi sint occaecati cupiditate non provident, similique sunt in culpa qui officia deserunt mollitia animi, id est laborum et dolorum fuga.
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt.
At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis praesentium voluptatum deleniti atque corrupti quos dolores et quas molestias excepturi sint occaecati cupiditate non provident, similique sunt in culpa qui officia deserunt mollitia animi, id est laborum et dolorum fuga.
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt.
At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis praesentium voluptatum deleniti atque corrupti quos dolores et quas molestias excepturi sint occaecati cupiditate non provident, similique sunt in culpa qui officia deserunt mollitia animi, id est laborum et dolorum fuga.
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt.
At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis praesentium voluptatum deleniti atque corrupti quos dolores et quas molestias excepturi sint occaecati cupiditate non provident, similique sunt in culpa qui officia deserunt mollitia animi, id est laborum et dolorum fuga.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
This is a nested scroll area. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
This is a nested scroll area. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.
Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
This is a nested scroll area. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.
Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
This is a nested scroll area. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.
Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem.
` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Scrollbar Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `orientation` | `Orientation` | No | | **Scrollbar Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | scroll-area | | `[data-part]` | scrollbar | | `[data-orientation]` | The orientation of the scrollbar | | `[data-scrolling]` | Present when scrolling | | `[data-hover]` | Present when hovered | | `[data-dragging]` | Present when in the dragging state | | `[data-overflow-x]` | Present when the content overflows the x-axis | | `[data-overflow-y]` | Present when the content overflows the y-axis | **Thumb Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Thumb Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | scroll-area | | `[data-part]` | thumb | | `[data-orientation]` | The orientation of the thumb | | `[data-hover]` | Present when hovered | | `[data-dragging]` | Present when in the dragging state | **Viewport Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Viewport Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | scroll-area | | `[data-part]` | viewport | | `[data-at-top]` | Present when scrolled to the top edge | | `[data-at-bottom]` | Present when scrolled to the bottom edge | | `[data-at-left]` | Present when scrolled to the left edge | | `[data-at-right]` | Present when scrolled to the right edge | | `[data-overflow-x]` | Present when the content overflows the x-axis | | `[data-overflow-y]` | Present when the content overflows the y-axis | #### Svelte **Root 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. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string; viewport: string; content: string; scrollbar: string; thumb: string }>` | No | The ids of the scroll area elements | | `ref` | `Element` | No | | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | scroll-area | | `[data-part]` | root | | `[data-overflow-x]` | Present when the content overflows the x-axis | | `[data-overflow-y]` | Present when the content overflows the y-axis | **Content 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. | | `ref` | `Element` | No | | **Content Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | scroll-area | | `[data-part]` | content | | `[data-overflow-x]` | Present when the content overflows the x-axis | | `[data-overflow-y]` | Present when the content overflows the y-axis | **Context Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `render` | `Snippet<[UseScrollAreaContext]>` | Yes | | **Corner 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. | | `ref` | `Element` | No | | **Corner Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | scroll-area | | `[data-part]` | corner | | `[data-hover]` | Present when hovered | | `[data-state]` | "hidden" | "visible" | | `[data-overflow-x]` | Present when the content overflows the x-axis | | `[data-overflow-y]` | Present when the content overflows the y-axis | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseScrollAreaContext` | Yes | | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Scrollbar 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. | | `orientation` | `Orientation` | No | | | `ref` | `Element` | No | | **Scrollbar Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | scroll-area | | `[data-part]` | scrollbar | | `[data-orientation]` | The orientation of the scrollbar | | `[data-scrolling]` | Present when scrolling | | `[data-hover]` | Present when hovered | | `[data-dragging]` | Present when in the dragging state | | `[data-overflow-x]` | Present when the content overflows the x-axis | | `[data-overflow-y]` | Present when the content overflows the y-axis | **Thumb 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. | | `ref` | `Element` | No | | **Thumb Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | scroll-area | | `[data-part]` | thumb | | `[data-orientation]` | The orientation of the thumb | | `[data-hover]` | Present when hovered | | `[data-dragging]` | Present when in the dragging state | **Viewport 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. | | `ref` | `Element` | No | | **Viewport Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | scroll-area | | `[data-part]` | viewport | | `[data-at-top]` | Present when scrolled to the top edge | | `[data-at-bottom]` | Present when scrolled to the bottom edge | | `[data-at-left]` | Present when scrolled to the left edge | | `[data-at-right]` | Present when scrolled to the right edge | | `[data-overflow-x]` | Present when the content overflows the x-axis | | `[data-overflow-y]` | Present when the content overflows the y-axis | ### Context These are the properties available when using `ScrollArea.Context`, `useScrollAreaContext` hook or `useScrollArea` hook. **API:** | Property | Type | Description | |----------|------|-------------| | `isAtTop` | `boolean` | Whether the scroll area is at the top | | `isAtBottom` | `boolean` | Whether the scroll area is at the bottom | | `isAtLeft` | `boolean` | Whether the scroll area is at the left | | `isAtRight` | `boolean` | Whether the scroll area is at the right | | `hasOverflowX` | `boolean` | Whether the scroll area has horizontal overflow | | `hasOverflowY` | `boolean` | Whether the scroll area has vertical overflow | | `getScrollProgress` | `() => Point` | Get the scroll progress as values between 0 and 1 | | `scrollToEdge` | `(details: ScrollToEdgeDetails) => void` | Scroll to the edge of the scroll area | | `scrollTo` | `(details: ScrollToDetails) => void` | Scroll to specific coordinates | | `getScrollbarState` | `(props: ScrollbarProps) => ScrollbarState` | Returns the state of the scrollbar | # Segment Group ## Anatomy To set up the segmented control correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples Learn how to use the `SegmentGroup` component in your project. Let's take a look at the most basic example: **Example: basic** #### React ```tsx import { SegmentGroup } from '@ark-ui/react/segment-group' export const Basic = () => { const frameworks = ['React', 'Solid', 'Svelte', 'Vue'] return ( {frameworks.map((framework) => ( {framework} {(framework) => ( {framework()} {{ framework }} {#each frameworks as framework} {framework} {frameworks.map((framework) => ( {framework} {(framework) => ( {framework()} {{ framework }} {#each frameworks as framework (framework)} {framework} ('React') return ( setValue(e.value)}> ) } ``` #### Solid ```tsx import { SegmentGroup } from '@ark-ui/solid/segment-group' import { Index, createSignal } from 'solid-js' export const Controlled = () => { const frameworks = ['React', 'Solid', 'Svelte', 'Vue'] const [value, setValue] = createSignal{frameworks.map((framework) => ( {framework} ('React') return ( setValue(e.value)}> ) } ``` #### Vue ```vue{(framework) => ( {framework()} {{ framework }} {#each frameworks as framework} {framework} {frameworks.map((framework) => ( {framework} {(framework) => ( {framework()} {{ framework }} {#each frameworks as framework} {framework} {frameworks.map((framework) => ( {framework} {(framework) => ( {framework()} {{ framework }} {#each frameworks as framework} {framework} ## Accessibility Complies with the [Radio WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/). ### Keyboard Support **`Tab`** Description: Moves focus to either the checked radio item or the first radio item in the group. **`Space`** Description: When focus is on an unchecked radio item, checks it. **`ArrowDown`** Description: Moves focus and checks the next radio item in the group. **`ArrowRight`** Description: Moves focus and checks the next radio item in the group. **`ArrowUp`** Description: Moves focus to the previous radio item in the group. **`ArrowLeft`** Description: Moves focus to the previous radio item in the group. # Select ## Anatomy To set up the select correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples Learn how to use the `Select` component in your project. Let's take a look at the most basic example: **Example: basic** #### React ```tsx import { Portal } from '@ark-ui/react/portal' import { Select, createListCollection } from '@ark-ui/react/select' import { ChevronDownIcon } from 'lucide-react' export const Basic = () => { const collection = createListCollection({ items: ['React', 'Solid', 'Vue', 'Svelte'] }) return ( Framework Clear Frameworks {collection.items.map((item) => ({item} ✓ Framework ▼ Clear Frameworks {(item) => ( {item()} ✓ Framework Clear Frameworks {{ item }} ✓ Framework Clear Frameworks {#each collection.items as item}{item} ✓ - ({ items: [ { label: 'React', value: 'react' }, { label: 'Solid', value: 'solid' }, { label: 'Vue', value: 'vue' }, { label: 'Svelte', value: 'svelte', disabled: true }, ], }) const handleValueChange = (details: Select.ValueChangeDetails
- ) => { setValue(details.value) } return (
Framework Clear Frameworks {collection.items.map((item) => ({item.label} ✓ - ({ items: [ { label: 'React', value: 'react' }, { label: 'Solid', value: 'solid' }, { label: 'Vue', value: 'vue' }, { label: 'Svelte', value: 'svelte', disabled: true }, ], }) const handleValueChange = (details: Select.ValueChangeDetails
- ) => { setValue(details.value) } return (
Framework Clear Frameworks {(item) => ( {item().label} ✓ Framework Clear Frameworks {{ item.label }} ✓ Framework Clear Frameworks {#each collection.items as item (item.value)}{item.label} ✓ {/if} ``` ### Grouping Grouping related options can be useful for organizing options into categories. - Use the `groupBy` prop to configure the grouping of the items. - Use the `collection.group()` method to get the grouped items. - Use the `Select.ItemGroup` and `Select.ItemGroupLabel` components to render the grouped items. **Example: grouping** #### React ```tsx import { Portal } from '@ark-ui/react/portal' import { Select, createListCollection } from '@ark-ui/react/select' import { ChevronDownIcon } from 'lucide-react' export const Grouping = () => { const collection = createListCollection({ items: [ { label: 'React', value: 'react', type: 'JS' }, { label: 'Solid', value: 'solid', type: 'JS' }, { label: 'Vue', value: 'vue', type: 'JS' }, { label: 'Panda', value: 'panda', type: 'CSS' }, { label: 'Tailwind', value: 'tailwind', type: 'CSS' }, ], groupBy: (item) => item.type, }) return (Selected: {selectedItems.map((item) => item.label).join(', ')}
Framework Clear {collection.group().map(([type, group]) => ( {type} {group.map((item) => ({item.label} ✓ Framework Clear {([type, group]) => ( {type} {(item) => ( {item.label} ✓ Framework Clear {{ type }} {{ item.label }} ✓ Framework Clear {#each collection.group() as [type, group]} {type} {#each group as item (item.value)}{item.label} ✓ Framework Clear Frameworks {collection.items.map((item) => ({item.label} ✓ Framework Clear Frameworks {(item) => ( {item().label} ✓ Framework Clear Frameworks {{ item.label }} ✓ Framework Clear Frameworks {#each collection.items as item (item.value)}{item.label} ✓ ({ defaultValues: { framework: 'React' }, }) const collection = createListCollection({ items: ['React', 'Solid', 'Vue', 'Svelte'], }) const onSubmit: SubmitHandler = (data) => { window.alert(JSON.stringify(data)) } return ( ) } ``` #### Solid ```tsx import { Select, createListCollection } from '@ark-ui/solid' import { createForm, getValue, setValue } from '@modular-forms/solid' import { createMemo } from 'solid-js' import { Index, Portal } from 'solid-js/web' export const FormLibrary = () => { const frameworks = createListCollection({ items: [ { label: 'React', value: 'react' }, { label: 'Solid', value: 'solid' }, { label: 'Vue', value: 'vue' }, ], }) const [formStore, { Form, Field }] = createForm({ initialValues: { value: 'solid' }, }) const value = createMemo(() => getValue(formStore, 'value')) return ( <> Value is {value()}) } ``` #### Vue ```vue``` #### Svelte ```svelteValue is {{ values.framework }}Value is {formData.framework}``` ### Field Component The `Field` component helps manage form-related state and accessibility attributes of a select. It includes handling ARIA labels, helper text, and error text to ensure proper accessibility. **Example: with-field** #### React ```tsx import { Field } from '@ark-ui/react/field' import { Select, createListCollection } from '@ark-ui/react/select' import { ChevronDownIcon } from 'lucide-react' export const WithField = (props: Field.RootProps) => { const collection = createListCollection({ items: ['React', 'Solid', 'Vue', 'Svelte'] }) return (Label {collection.items.map((item) => ( {item} ✓ Additional Info Error Info Label Frameworks {(item) => ( {item()} ✓ Additional Info Error Info Label Clear Frameworks {{ item }} ✓ Additional Info Error Info Framework {#each collection.items as item} {item} ✓ Additional Info Error Info (null) const collection = createListCollection ({ items: items || [], }) const handleOpenChange = (details: Select.OpenChangeDetails) => { if (details.open && items == null) { setLoading(true) setError(null) loadData() .then((data) => setItems(data)) .catch((err) => setError(err)) .finally(() => setLoading(false)) } } return ( Framework Clear {loading ? ( Loading...) : error ? (Error: {error.message}) : ( collection.items.map((item) => ({item} ✓ (null) const collection = createMemo(() => createListCollection ({ items: items() || [], }), ) const handleOpenChange = (details: Select.OpenChangeDetails) => { if (details.open && items() === null) { setLoading(true) setError(null) loadData() .then((data) => setItems(data)) .catch((err) => setError(err)) .finally(() => setLoading(false)) } } return ( Framework ▼ Clear Loading...Error: {error()?.message}{(item) => ( {item()} ✓ Framework Clear Loading...Error: {{ error.message }}{{ item }} ✓ Framework Clear {#if loading} Loading...{:else if error}Error: {error.message}{:else} {#each collection.items as item}{item} ✓ Framework Clear Frameworks {collection.items.map((item) => ({item} ✓ Framework ▼ Clear Frameworks {(item) => ( {item()} ✓ Framework Clear Frameworks {{ item }} ✓ ``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ### Select on Highlight Here's an example of automatically selecting items when they are highlighted (hovered or navigated to with keyboard). **Example: select-on-highlight** #### React ```tsx import { Portal } from '@ark-ui/react/portal' import { Select, createListCollection, useSelect } from '@ark-ui/react/select' import { ChevronDownIcon } from 'lucide-react' export const SelectOnHighlight = () => { const collection = createListCollection({ items: ['React', 'Solid', 'Vue', 'Svelte'], }) const select = useSelect({ collection, onHighlightChange({ highlightedValue }) { if (highlightedValue) { select.selectValue(highlightedValue) } }, }) return (Framework Clear Frameworks {#each collection.items as item}{item} ✓ Framework Clear Frameworks {collection.items.map((item) => ({item} ✓ Framework ▼ Clear Frameworks {(item) => ( {item()} ✓ Framework Clear Frameworks {{ item }} ✓ Framework Clear Frameworks {#each collection.items as item}{item} ✓ Framework Clear Frameworks {collection.items.map((item) => ({item.label} ✓ Framework ▼ Clear Frameworks {(item) => ( {item().label} ✓ Framework Clear Frameworks {{ item.label }} ✓ Framework Clear Frameworks {#each collection.items as item (item.value)}{item.label} ✓ Framework Clear Frameworks {collection.items.map((item) => ({item} ✓ Framework ▼ Clear Frameworks {(item) => ( {item()} ✓ Framework Clear Frameworks {{ item }} ✓ Framework Clear Frameworks {#each collection.items as item}{item} ✓ extends ArkSelect.RootProps {} const Select: ArkSelect.RootComponent = (props) => { return {/* ... */} } ``` Then, you can use the `Select` component as follows: ```tsx const App = () => { const collection = createListCollection({ initialItems: [ { label: 'React', value: 'react' }, { label: 'Vue', value: 'vue' }, { label: 'Svelte', value: 'svelte' }, ], }) return ( ) } ``` ### Usage in Popover or Dialog When using the Select component within a `Popover` or `Dialog`, avoid rendering its content within a `Portal` or `Teleport`. This ensures the Select's content stays within the Popover/Dialog's DOM hierarchy rather than being portalled to the document body, maintaining proper interaction and accessibility behavior. ### Hidden Select The `Select.HiddenSelect` component renders a native HTML ` - ({ initialItems: [ { label: 'React', value: 'react' }, { label: 'Solid', value: 'solid' }, { label: 'Vue', value: 'vue' }, { label: 'Svelte', value: 'svelte' }, ], filter: filterFn().contains, }) const isValidNewOption = (inputValue: string) => { const exactOptionMatch = collection().items.filter((item) => item.label.toLowerCase() === inputValue.toLowerCase()).length > 0 return !exactOptionMatch && inputValue.trim().length > 0 } const [selectedValue, setSelectedValue] = createSignal
- `.
- **Textarea**: Fixed `ResizeObserver` warning.
- **Timer**: Fixed stopping issue when switching tabs; resolved issue where `action` prop was passed to `ActionTrigger`.
- **Toast**: Fixed keyboard navigation skipping close button.
- **Toggle Group**: Fixed `data-focus` not being removed on blur.
# About
## Acknowledgments
We are committed to open source and the power of collaboration. Our work has been inspired by numerous projects and
individuals who continually drive us to innovate and improve.
- [Zag.js](https://zagjs.com/) - The foundation of this project
- [Park UI](https://park-ui.com) - For providing the styled component demos featured in this project
- [Radix Vue](https://www.radix-vue.com/) - For `useForwardPropsEmits`, which we re-export to build closed Vue
components
## License
This project is licensed under the terms of the [MIT license](https://github.com/chakra-ui/ark/blob/main/LICENSE).
# GUIDES
---
# Animation
Adding animation to Ark UI Components is as straightforward as with any other component, but keep in mind some
considerations when working with exit animations with JavaScript animation libraries.
## Animating with CSS
The most straightforward method to animate your elements is using CSS. You can animate both the mounting and unmounting
phases with CSS. The latter is achievable because Ark UI Components postpones the unmounting while your animation runs.
Below is a simple example of creating a fade-in and fade-out animation using CSS keyframes:
```css
@keyframes fadeIn {
from {
opacity: 0;
}
to {
opacity: 1;
}
}
@keyframes fadeOut {
from {
opacity: 1;
}
to {
opacity: 0;
}
}
```
You can use these keyframes to animate any element during its lifecycle. For instance, to apply the `fadeIn` animation
when your `Tooltip` enters the 'open' state, and `fadeOut` when it enters the 'closed' state, you could use the
following styles:
```css
[data-scope='tooltip'][data-part='content'][data-state='open'] {
animation: fadeIn 300ms ease-out;
}
[data-scope='tooltip'][data-part='content'][data-state='closed'] {
animation: fadeOut 300ms ease-in;
}
```
## Animating with JS Libraries
There's plenty of versatility when it comes to animating your Ark UI Elements with JavaScript libraries. Various
libraries such as GreenSock, anime.js, Framer Motion, and more can add a new level of interaction and feedback to your
UI components.
One significant advantage of using Ark UI Elements is the control you have over the unmounting phase of your components.
This is primarily facilitated through the `present` prop. The `present` prop allows the component to stay mounted even
after its enclosing condition has been falsified, allowing for exit animations to complete before the component is
removed from the DOM.
# Closed Components
## Motivation
Writing a few lines of code every time you need a simple `Avatar` is tedious. Creating a dedicated component
encapsulates logic, simplifies the API, ensures consistent usage, and maintains clean code. This approach enhances
reusability, making the component easier to maintain and test.
Here's an example of an `Avatar` component that can be used consistently across your application:
**Example: closed**
#### React
```tsx
import { Avatar as ArkAvatar } from '@ark-ui/react/avatar'
import { UserIcon } from 'lucide-react'
import { forwardRef } from 'react'
export interface AvatarProps extends ArkAvatar.RootProps {
name?: string | undefined
src?: string | undefined
}
export const Avatar = forwardRef
{getInitials(name) || } }> {getInitials(localProps.name)} {{ getInitials }} {#if initials} {initials} {:else} {/if} ``` # Component State ## Context Components Context components expose state and functions to child components. In this example, `Avatar.Fallback` renders based on `loaded` state. **Example: context** #### React ```tsx import { Avatar } from '@ark-ui/react/avatar' export const Context = () => ( {(avatar) => {avatar.loaded ? 'PA' : 'Loading'} }{(avatar) => {avatar().loaded ? 'PA' : 'Loading'} }{{ avatar.loaded ? 'PA' : 'Loading' }} {#snippet api(avatar)} {#if avatar().loaded} {/snippet}PA
{:else}Loading
{/if}{['React', 'Solid', 'Vue', 'Svelte'].map((item) => ( ) } ``` #### Solid ```tsx import { Accordion, useAccordion } from '@ark-ui/solid/accordion' import { ChevronDownIcon } from 'lucide-solid' import { Index } from 'solid-js' export const RootProvider = () => { const accordion = useAccordion({ multiple: true, defaultValue: ['React'], }) return ( <>What is {item}? {item} is a JavaScript library for building user interfaces. {(item) => ( What is {item()}? {item()} is a JavaScript library for building user interfaces. What is {{ item }}? {{ item }} is a JavaScript library for building user interfaces. ``` > When using the `RootProvider` component, you don't need to use the `Root` component. See more in [Examples](/examples/popover-selection). # Composition ## The asChild Prop In Ark UI, the `asChild` prop lets you integrate custom components, ensuring consistent styling and behavior while promoting flexibility and reusability. All Ark components that render a DOM element accept the `asChild` prop. Here's an example using `asChild` to integrate a custom `Button` component within a `Popover`: **Example: as-child** #### React ```tsx import { Popover } from '@ark-ui/react/popover' export const AsChild = () => (Open items: {JSON.stringify(accordion().value)}{#each ['React', 'Solid', 'Vue', 'Svelte'] as item (item)} What is {item}? {item} is a JavaScript library for building user interfaces. }>Open {#snippet asChild(props)} {/snippet} Ark UI } > Ark UI Ark UI {#snippet asChild(props)} ``` This will produce the following HTML: ```html Ark UI ``` ## ID Composition When composing components that need to work together, share IDs between them using the `ids` prop for proper accessibility and interaction. ```tsx import { Avatar } from '@ark-ui/react/avatar' import { Tooltip } from '@ark-ui/react/tooltip' import { useId } from 'react' export const TooltipWithAvatar = () => { const id = useId() return (Ark UI {/snippet}SA Segun Adebayo is online {/* NumberInput will be disabled */} (required) ``` ### Native Controls Field supports native HTML form controls including `input`, `textarea`, and `select`: ```tsx import { Field } from '@ark-ui/react/field' const Demo = () => ( ) ``` ### Form Reset When the `reset` event is triggered on a form, all Ark UI components automatically sync their internal state with the form's reset values. > **Note**: For this to work correctly, always include the `HiddenInput` component in your form controls. The hidden > input participates in the native form reset mechanism, and Ark UI listens for this to sync the component state. ```tsx import { Checkbox } from '@ark-ui/react/checkbox' const Demo = () => { return ( ) } ``` ## Fieldset Context When you have multiple fields in a form or a component that renders multiple `input` elements, you can use the `Fieldset` component to group them together. Common use cases checkbox group, radio group, input + select composition, etc. ### Checkbox Group ```tsx import { Fieldset } from '@ark-ui/react/fieldset' import { Checkbox } from '@ark-ui/react/checkbox' import { CheckIcon } from 'lucide-react' const items = [ { label: 'React', value: 'react' }, { label: 'Solid', value: 'solid' }, { label: 'Vue', value: 'vue' }, { label: 'Svelte', value: 'svelte' }, ] const Demo = () => (Frameworks {items.map((item) => ( ))} Choose your preferred frameworks Frameworks {items.map((item) => ( ))} Choose your preferred framework () const onSubmit = (data: FormValues) => console.log(data) return ( ) } ``` ### Custom Components Use the `Controller` hook to integrate custom form components like select or combobox. > **Best practice**: To ensure `react-hook-form` moves focus to invalid field control when performing validation, > forward the field's `ref` to the respective Ark UI component. ```tsx import { Field } from '@ark-ui/react/field' import { Select, createListCollection } from '@ark-ui/react/select' import { Controller, useForm } from 'react-hook-form' const Demo = () => { const { control, handleSubmit } = useForm({ defaultValues: { framework: '' }, }) const collection = createListCollection({ items: ['React', 'Solid', 'Vue', 'Svelte'], }) return ( ) } ``` ## TanStack Form TanStack Form provides powerful form state management that works well with Ark UI. ### Native Controls ```tsx import { useForm } from '@tanstack/react-form' const form = useForm({ defaultValues: { firstName: '' }, }) const Demo = () => ( ) ``` ### Custom Components Here's an example of how to integrate custom components like the select or combobox with Tanstack's `form.Field` component. ```tsx import { Field } from '@ark-ui/react/field' import { Select, createListCollection } from '@ark-ui/react/select' import { useForm } from '@tanstack/react-form' const Demo = () => { const form = useForm({ defaultValues: { username: '' }, }) const collection = createListCollection({ items: ['React', 'Solid', 'Vue', 'Svelte'], }) return ( ) } ``` # Refs ## React In React, the `ref` prop can be used to access the rendered element. Use the `useRef` hook to create a reference and pass it to the component. ```tsx import { Slider } from '@ark-ui/react/slider' import { useRef } from 'react' export const MySlider = () => { const rootRef = useRef (null) return {/* ... */} } ``` ## Solid In Solid, the `ref` prop can be used to access the rendered element. ```tsx import { Slider } from '@ark-ui/solid/slider' export const MySlider = () => { let rootRef!: HTMLDivElement return(rootRef = el)}>{/* ... */} } ``` Alternatively, you can assign refs to Solid.js signals via the `createSignal` function. ```tsx import { Slider } from '@ark-ui/solid/slider' import { createSignal } from 'solid-js' export const MySlider = () => { const [rootRef, setRootRef] = createSignal(null) return {/* ... */} } ``` ## Vue In Vue, pass the `ref` prop to the component to access the rendered element via the `$el` property. ```vue{/* ... */} ``` ## Svelte In Svelte 5, use the `bind:ref` directive to access the rendered element. ```svelte{/* ... */} ``` # Styling ## Overview Ark UI is a headless component library that works with any styling solution. It provides functional styles for elements like popovers for positioning, while leaving presentation styles up to you. Some components also expose CSS variables that can be used for styling or animations. > **Tip:** Looking for a ready-to-use solution? Checkout [Park UI](https://park-ui.com) for a collection of pre-designed > styles based on Ark UI components. ### Data Attributes Ark UI components use `data-scope` and `data-part` attributes to target specific elements within a component. Interactive components often include `data-*` attributes to indicate their state. For example, here's what an open accordion item looks like: ```html ``` For more details on each component's data attributes, refer to their respective documentation. ## Styling with CSS When styling components with CSS, you can target the data attributes assigned to each component part for easy customization. ### Styling a Part To style a specific component part, target its `data-scope` and `data-part` attributes: ```css [data-scope='accordion'][data-part='item'] { border-bottom: 1px solid #e5e5e5; } ``` ### Styling a State To style a component based on its state, use the `data-state` attribute: ```css [data-scope='accordion'][data-part='item'][data-state='open'] { background-color: #f5f5f5; } ``` > **Tip:** If you prefer using classes instead of data attributes, utilize the `class` or `className` prop to add custom > classes to Ark UI components. ### Class Names If you prefer using classes instead of data attributes, utilize `class` or `className` prop to add custom classes to Ark UI components. Pass a class: ```jsx{/* … */} /anatomy` entrypoint (e.g., > `@ark-ui/react/anatomy`) instead of the main package export to avoid potential build and import errors. ```ts import { accordionAnatomy } from '@ark-ui/react/anatomy' import { defineSlotRecipe } from '@pandacss/dev' export const accordionStyles = defineSlotRecipe({ className: 'accordion', slots: accordionAnatomy.keys(), base: { item: { borderBottom: '1px solid #e5e5e5', }, }, defaultVariants: {}, variants: {}, }) ``` ### Styling a state To style a component based on its state, you can use built in [conditions](https://panda-css.com/docs/customization/conditions) in Panda CSS. ```ts import { accordionAnatomy } from '@ark-ui/react/anatomy' import { defineSlotRecipe } from '@pandacss/dev' export const accordionStyles = defineSlotRecipe({ className: 'accordion', slots: accordionAnatomy.keys(), base: { item: { borderBottom: '1px solid {colors.gray.300}', _open: { // [!code highlight] backgroundColor: 'gray.100', }, }, }, defaultVariants: {}, variants: {}, }) ``` ## Styling with Tailwind CSS [Tailwind CSS](https://tailwindcss.com/) is a utility-first CSS framework providing a flexible way to style your components. ### Styling a Part To style a part, apply classes directly to the parts using either `class` or `className`, depending on the JavaScript framework. ```jsx {/* … */} {/* … */} 
It works with tools like Claude Code, Cursor, and Copilot to generate code and apply design system logic consistently
across React, Vue, Solid, and Svelte.
## Tools
The Ark UI MCP exposes the following tools to AI agents:
- **`list_components`**: Returns a full list of all available components
- **`list_examples`**: Lists various component examples
- **`get_example`**: Retrieves code examples and usage patterns
- **`styling_guide`**: Provides styling guidelines for components (data attributes and CSS variables)
## Setup
The MCP server currently supports only
[stdio transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio) and is published at
`@ark-ui/mcp`.
### Visual Studio Code
> Make sure you have the [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) and
> [GitHub Copilot Chat](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat) extensions installed.
- In the `.vscode/mcp.json` file at the root of your project, add the MCP server block:
```json title=".vscode/mcp.json"
{
"servers": {
"ark-ui": {
"command": "npx",
"args": ["-y", "@ark-ui/mcp"]
}
}
}
```
- The MCP server is now ready to use. Click the **"Start"** button in the `mcp.json` file.
- Start a new chat VSCode Copilot like _"Build me a checkbox with ark ui"_
### Cursor
- In the `.cursor/mcp.json` file at the root of your project, add the following configuration:
```json
{
"mcpServers": {
"ark-ui": {
"command": "npx",
"args": ["-y", "@ark-ui/mcp"]
}
}
}
```
- Go to **Settings** > **Cursor Settings** > **MCP & Integrations** and enable the Ark UI server.
- Start a new chat Cursor chat like _"Build me a checkbox with ark ui"_
### Claude Code
> Make sure you have Claude Code installed. Visit [Anthropic docs](https://docs.anthropic.com/en/docs/claude-code/mcp)
> for installation instructions.
- Run the following command in your terminal to add the Ark UI MCP server:
```bash
claude mcp add ark-ui -- npx -y @ark-ui/mcp
```
- Start a Claude Code session by running `claude`
- Type a prompt like _"Build me a checkbox with ark ui"_
### Windsurf
- Navigate to **Settings** > **Windsurf Settings** > **Cascade**
- Click the **Manage MCPs** button, then click the **"View raw config"** button.
- Add the following to the MCP configuration file:
```json title=".codeium/windsurf/mcp_config.json"
{
"mcpServers": {
"ark-ui": {
"command": "npx",
"args": ["-y", "@ark-ui/mcp"]
}
}
}
```
> You might need to click the **Refresh** button to see the MCP server in the list.
- Start a new chat Windsurf like _"Build me a checkbox with ark ui"_
### Zed
- Go to **Settings** > **Open Settings**
- In the `settings.json` file, add MCP server as a new **context server**:
```json title=".config/zed/settings.json"
{
"context_servers": {
"ark-ui": {
"source": "custom",
"command": "npx",
"args": ["-y", "@ark-ui/mcp"]
}
}
}
```
- Start a new chat Zed like _"Build me a checkbox with ark ui"_
### Custom MCP Client
To run the MCP server in a local or development environment using a custom MCP client, you need to add the MCP server to
the client's configuration file.
```json
{
"mcpServers": {
"ark-ui": {
"command": "npx",
"args": ["-y", "@ark-ui/mcp"]
}
}
}
```
# COLLECTIONS
---
# Async List
The `useAsyncList` hook manages asynchronous data operations for list collections. It provides a comprehensive solution
for loading, filtering, sorting, and paginating data with built-in loading states, error handling, and request
cancellation.
```tsx
import { useAsyncList } from '@ark-ui/react/collection'
const list = useAsyncList({ async load({ signal }) { const response = await fetch('/api/users', { signal }) const users = await response.json() return { items: users } }, }) console.log(list.items) // User[] console.log(list.loading) // boolean console.log(list.error) // Error | null ``` ## Examples ### Basic Usage The most basic usage involves providing a `load` function that returns data. **Example: async-list/reload** #### React ```tsx import { useAsyncList } from '@ark-ui/react/collection' interface Quote { id: number quote: string author: string } export const Reload = () => { const list = useAsyncList ({ async load() { const response = await fetch(`https://dummyjson.com/quotes?limit=5&skip=${Math.floor(Math.random() * 50)}`) if (!response.ok) { throw new Error('Failed to fetch quotes') } const data = await response.json() return { items: data.quotes } }, }) return (
) } ``` #### Solid ```tsx import { useAsyncList } from '@ark-ui/solid/collection' import { For } from 'solid-js' interface Quote { id: number quote: string author: string } export const Reload = () => { const list = useAsyncList{list.error &&Error: {list.error.message}}{list.items.map((quote) => ())}"{quote.quote}"— {quote.author}({ async load() { const response = await fetch(`https://dummyjson.com/quotes?limit=5&skip=${Math.floor(Math.random() * 50)}`) if (!response.ok) { throw new Error('Failed to fetch quotes') } const data = await response.json() return { items: data.quotes } }, }) return (
) } ``` #### Vue ```vue{list().error &&Error: {list().error.message}}{(quote) => ( )}"{quote.quote}"— {quote.author}``` #### Svelte ```svelteError: {{ list.error.message }}"{{ quote.quote }}"— {{ quote.author }}``` ### Infinite Loading Implement pagination by returning a cursor that indicates more data is available. **Example: async-list/infinite-loading** #### React ```tsx import { useAsyncList } from '@ark-ui/react/collection' interface Post { userId: number id: number title: string body: string } export const InfiniteLoading = () => { const list = useAsyncList{#if list().error}Error: {list().error.message}{/if}{#each list().items as quote}{/each}"{quote.quote}"— {quote.author}) } ``` #### Solid ```tsx import { useAsyncList } from '@ark-ui/solid/collection' import { For } from 'solid-js' interface Post { userId: number id: number title: string body: string } export const InfiniteLoading = () => { const list = useAsyncListLoaded {list.items.length} posts {list.cursor && ` (more available)`}{list.cursor && ( )} {list.error &&Error: {list.error.message}}{list.items.map((post, index) => ())}{index + 1}: {post.title}{post.body}) } ``` #### Vue ```vueLoaded {list().items.length} posts {list().cursor && ` (more available)`}{list().cursor && ( )} {list().error &&Error: {list().error.message}}{(post, index) => ( )}{index() + 1}: {post.title}{post.body}``` #### Svelte ```svelteLoaded {{ list.items.length }} posts (more available)Error: {{ list.error.message }}{{ index + 1 }}: {{ post.title }}{{ post.body }}``` ### Filtering Filter data based on user input with automatic debouncing and loading states. **Example: async-list/filter** #### React ```tsx import { useAsyncList } from '@ark-ui/react/collection' interface User { id: number name: string email: string department: string role: string } export const Filter = () => { const list = useAsyncListLoaded {list().items.length} posts {#if list().cursor}(more available){/if}{#if list().cursor} {/if} {#if list().error}Error: {list().error.message}{/if}{#each list().items as post, index}{/each}{index + 1}: {post.title}{post.body}({ initialItems: mockUsers.slice(0, 5), // Show first 5 users initially async load({ filterText }) { await delay(500) // Simulate network delay if (!filterText) { return { items: mockUsers.slice(0, 5) } } const filtered = mockUsers.filter( (user) => user.name.toLowerCase().includes(filterText.toLowerCase()) || user.email.toLowerCase().includes(filterText.toLowerCase()), ) return { items: filtered } }, }) return ( ) } const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)) const mockUsers: User[] = [ { id: 1, name: 'Alice Johnson', email: 'alice@example.com', department: 'Engineering', role: 'Senior Developer' }, { id: 2, name: 'Bob Smith', email: 'bob@example.com', department: 'Marketing', role: 'Marketing Manager' }, { id: 3, name: 'Carol Davis', email: 'carol@example.com', department: 'Engineering', role: 'Frontend Developer' }, { id: 4, name: 'David Wilson', email: 'david@example.com', department: 'Sales', role: 'Sales Representative' }, { id: 5, name: 'Eva Brown', email: 'eva@example.com', department: 'Engineering', role: 'DevOps Engineer' }, { id: 6, name: 'Frank Miller', email: 'frank@example.com', department: 'Support', role: 'Customer Success' }, { id: 7, name: 'Grace Lee', email: 'grace@example.com', department: 'Marketing', role: 'Content Creator' }, { id: 8, name: 'Henry Taylor', email: 'henry@example.com', department: 'Engineering', role: 'Backend Developer' }, { id: 9, name: 'Ivy Anderson', email: 'ivy@example.com', department: 'Sales', role: 'Account Manager' }, { id: 10, name: 'Jack Thompson', email: 'jack@example.com', department: 'Support', role: 'Technical Support' }, { id: 11, name: 'Kate Martinez', email: 'kate@example.com', department: 'Marketing', role: 'Brand Manager' }, { id: 12, name: 'Liam Garcia', email: 'liam@example.com', department: 'Engineering', role: 'Full Stack Developer' }, { id: 13, name: 'Mia Rodriguez', email: 'mia@example.com', department: 'Sales', role: 'Sales Director' }, { id: 14, name: 'Noah Lopez', email: 'noah@example.com', department: 'Support', role: 'Support Manager' }, { id: 15, name: 'Olivia White', email: 'olivia@example.com', department: 'Engineering', role: 'UI Designer' }, { id: 16, name: 'Paul Harris', email: 'paul@example.com', department: 'Marketing', role: 'Digital Marketer' }, { id: 17, name: 'Quinn Clark', email: 'quinn@example.com', department: 'Engineering', role: 'Mobile Developer' }, { id: 18, name: 'Ruby Lewis', email: 'ruby@example.com', department: 'Sales', role: 'Business Development' }, { id: 19, name: 'Sam Young', email: 'sam@example.com', department: 'Support', role: 'Documentation Specialist' }, { id: 20, name: 'Tina Walker', email: 'tina@example.com', department: 'Marketing', role: 'Social Media Manager' }, ] ``` #### Solid ```tsx import { useAsyncList } from '@ark-ui/solid/collection' import { For } from 'solid-js' interface User { id: number name: string email: string department: string role: string } export const Filter = () => { const list = useAsyncListlist.setFilterText(e.target.value)} /> {list.loading && Loading...}{list.error &&Error: {list.error.message}}{list.items.map((user) => ({list.items.length === 0 && !list.loading &&))}{user.name}{user.email}{user.department} • {user.role}No results found}({ initialItems: mockUsers.slice(0, 5), async load({ filterText }: { filterText?: string }) { await delay(500) if (!filterText) { return { items: mockUsers.slice(0, 5) } } const filtered = mockUsers.filter( (user) => user.name.toLowerCase().includes(filterText.toLowerCase()) || user.email.toLowerCase().includes(filterText.toLowerCase()), ) return { items: filtered } }, }) return ( ) } const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)) const mockUsers: User[] = [ { id: 1, name: 'Alice Johnson', email: 'alice@example.com', department: 'Engineering', role: 'Senior Developer' }, { id: 2, name: 'Bob Smith', email: 'bob@example.com', department: 'Marketing', role: 'Marketing Manager' }, { id: 3, name: 'Carol Davis', email: 'carol@example.com', department: 'Engineering', role: 'Frontend Developer' }, { id: 4, name: 'David Wilson', email: 'david@example.com', department: 'Sales', role: 'Sales Representative' }, { id: 5, name: 'Eva Brown', email: 'eva@example.com', department: 'Engineering', role: 'DevOps Engineer' }, { id: 6, name: 'Frank Miller', email: 'frank@example.com', department: 'Support', role: 'Customer Success' }, { id: 7, name: 'Grace Lee', email: 'grace@example.com', department: 'Marketing', role: 'Content Creator' }, { id: 8, name: 'Henry Taylor', email: 'henry@example.com', department: 'Engineering', role: 'Backend Developer' }, { id: 9, name: 'Ivy Anderson', email: 'ivy@example.com', department: 'Sales', role: 'Account Manager' }, { id: 10, name: 'Jack Thompson', email: 'jack@example.com', department: 'Support', role: 'Technical Support' }, { id: 11, name: 'Kate Martinez', email: 'kate@example.com', department: 'Marketing', role: 'Brand Manager' }, { id: 12, name: 'Liam Garcia', email: 'liam@example.com', department: 'Engineering', role: 'Full Stack Developer' }, { id: 13, name: 'Mia Rodriguez', email: 'mia@example.com', department: 'Sales', role: 'Sales Director' }, { id: 14, name: 'Noah Lopez', email: 'noah@example.com', department: 'Support', role: 'Support Manager' }, { id: 15, name: 'Olivia White', email: 'olivia@example.com', department: 'Engineering', role: 'UI Designer' }, { id: 16, name: 'Paul Harris', email: 'paul@example.com', department: 'Marketing', role: 'Digital Marketer' }, { id: 17, name: 'Quinn Clark', email: 'quinn@example.com', department: 'Engineering', role: 'Mobile Developer' }, { id: 18, name: 'Ruby Lewis', email: 'ruby@example.com', department: 'Sales', role: 'Business Development' }, { id: 19, name: 'Sam Young', email: 'sam@example.com', department: 'Support', role: 'Documentation Specialist' }, { id: 20, name: 'Tina Walker', email: 'tina@example.com', department: 'Marketing', role: 'Social Media Manager' }, ] ``` #### Vue ```vuelist().setFilterText(e.target.value)} /> {list().loading && Loading...}{list().error &&Error: {list().error.message}}{list().items.length === 0 && !list().loading &&{(user) => ( )}{user.name}{user.email}{user.department} • {user.role}No results found}``` #### Svelte ```svelteLoading...Error: {{ list.error.message }}{{ user.name }}{{ user.email }}{{ user.department }} • {{ user.role }}No results found``` ### Sorting (Client-side) Sort data on the client side after loading from the server. **Example: async-list/sort-client-side** #### React ```tsx import { useAsyncList } from '@ark-ui/react/collection' import { useCollator } from '@ark-ui/react/locale' interface User { id: number name: string username: string email: string phone: string website: string } export const SortClientSide = () => { const collator = useCollator() const list = useAsyncListlist().setFilterText(e.currentTarget.value)} /> {#if list().loading} Loading... {/if}{#if list().error}Error: {list().error.message}{/if}{#each list().items as user}{#if list().items.length === 0 && !list().loading}{/each}{user.name}{user.email}{user.department} • {user.role}No results found{/if}({ autoReload: true, load: async () => { const response = await fetch('https://jsonplaceholder.typicode.com/users') const data = await response.json() return { items: data } }, sort({ items, descriptor }) { return { items: items.sort((a, b) => { const { column, direction } = descriptor let cmp = collator.compare(String(a[column]), String(b[column])) if (direction === 'descending') { cmp *= -1 } return cmp }), } }, }) const handleSort = (column: keyof User) => { const currentSort = list.sortDescriptor let direction: 'ascending' | 'descending' = 'ascending' if (currentSort?.column === column && currentSort.direction === 'ascending') { direction = 'descending' } list.sort({ column, direction }) } const getSortIcon = (column: keyof User) => { const current = list.sortDescriptor if (current?.column !== column) return '↕️' return current.direction === 'ascending' ? '↑' : '↓' } const descriptor = list.sortDescriptor return ( ) } ``` #### Solid ```tsx import { useAsyncList } from '@ark-ui/solid/collection' import { useCollator } from '@ark-ui/solid/locale' import { For } from 'solid-js' interface User { id: number name: string username: string email: string phone: string website: string } export const SortClientSide = () => { const collator = useCollator() const list = useAsyncList{list.loading &&Loading...} {list.error &&Error: {list.error.message}}Sorted by: {descriptor ? `${descriptor.column} (${descriptor.direction})` : 'none'}{[ { key: 'name', label: 'Name' }, { key: 'username', label: 'Username' }, { key: 'email', label: 'Email' }, { key: 'phone', label: 'Phone' }, { key: 'website', label: 'Website' }, ].map(({ key, label }) => ( {list.items.map((user) => (handleSort(key as keyof User)}> {label} {getSortIcon(key as keyof User)} ))}{user.name} {user.username} {user.email} {user.phone} {user.website} ({ autoReload: true, load: async () => { const response = await fetch('https://jsonplaceholder.typicode.com/users') const data = await response.json() return { items: data } }, sort({ items, descriptor }) { return { items: items.sort((a, b) => { const { column, direction } = descriptor let cmp = collator().compare(String(a[column]), String(b[column])) if (direction === 'descending') { cmp *= -1 } return cmp }), } }, }) const handleSort = (column: keyof User) => { const currentSort = list().sortDescriptor let direction: 'ascending' | 'descending' = 'ascending' if (currentSort?.column === column && currentSort.direction === 'ascending') { direction = 'descending' } list().sort({ column, direction }) } const getSortIcon = (column: keyof User) => { const current = list().sortDescriptor if (current?.column !== column) return '↕️' return current.direction === 'ascending' ? '↑' : '↓' } const descriptor = () => list().sortDescriptor return ( ) } ``` #### Vue ```vue{list().loading &&Loading...} {list().error &&Error: {list().error.message}}Sorted by: {descriptor() ? `${descriptor()?.column} (${descriptor()?.direction})` : 'none'}{({ key, label }) => ( handleSort(key as keyof User)}> {label} {getSortIcon(key as keyof User)} )}{(user) => ( {user.name} {user.username} {user.email} {user.phone} {user.website} ``` #### Svelte ```svelteLoading...Error: {{ list.error.message }}Sorted by: {{ descriptor ? `${descriptor.column} (${descriptor.direction})` : 'none' }}{{ label }} {{ getSortIcon(key as keyof User) }} {{ user.name }} {{ user.username }} {{ user.email }} {{ user.phone }} {{ user.website }} ``` ### Sorting (Server-side) Send sort parameters to the server and reload data when sorting changes. **Example: async-list/sort-server-side** #### React ```tsx import { useAsyncList } from '@ark-ui/react/collection' interface Product { id: number title: string price: number description: string category: string image: string rating: { rate: number count: number } } export const SortServerSide = () => { const list = useAsyncList{#if list().loading}Loading...{/if} {#if list().error}Error: {list().error.message}{/if}Sorted by: {descriptor ? `${descriptor.column} (${descriptor.direction})` : 'none'}{#each [{ key: 'name', label: 'Name' }, { key: 'username', label: 'Username' }, { key: 'email', label: 'Email' }, { key: 'phone', label: 'Phone' }, { key: 'website', label: 'Website' }] as { key, label }} {#each list().items as user}handleSort(key as keyof User)}> {label} {getSortIcon(key as keyof User)} {/each}{user.name} {user.username} {user.email} {user.phone} {user.website} ({ autoReload: true, async load({ sortDescriptor }) { const url = new URL('https://fakestoreapi.com/products') if (sortDescriptor) { const { direction } = sortDescriptor url.searchParams.set('sort', direction === 'ascending' ? 'asc' : 'desc') } const response = await fetch(url) const items = await response.json() return { items } }, }) const handleSort = (column: keyof Product) => { const currentSort = list.sortDescriptor let direction: 'ascending' | 'descending' = 'ascending' if (currentSort?.column === column && currentSort.direction === 'ascending') { direction = 'descending' } list.sort({ column, direction }) } const getSortIcon = (column: keyof Product) => { const desc = list.sortDescriptor if (desc?.column !== column) return '↕️' return desc.direction === 'ascending' ? '↑' : '↓' } return ( {list.loading &&) } ``` #### Solid ```tsx import { useAsyncList } from '@ark-ui/solid/collection' import { For, Show } from 'solid-js' interface Product { id: number title: string price: number description: string category: string image: string rating: { rate: number count: number } } export const SortServerSide = () => { const list = useAsyncListLoading...} {list.error &&Error: {list.error.message}}{list.items.map((product) => ({list.sortDescriptor && ())}{product.title}${product.price}{product.category}{product.rating.rate} ({product.rating.count} reviews)Sorted by {list.sortDescriptor.column} ({list.sortDescriptor.direction}))}({ autoReload: true, async load({ sortDescriptor }) { const url = new URL('https://fakestoreapi.com/products') if (sortDescriptor) { const { direction } = sortDescriptor url.searchParams.set('sort', direction === 'ascending' ? 'asc' : 'desc') } const response = await fetch(url) const items = await response.json() return { items } }, }) const handleSort = (column: keyof Product) => { const currentSort = list().sortDescriptor let direction: 'ascending' | 'descending' = 'ascending' if (currentSort?.column === column && currentSort.direction === 'ascending') { direction = 'descending' } list().sort({ column, direction }) } const getSortIcon = (column: keyof Product) => { const desc = list().sortDescriptor if (desc?.column !== column) return '↕️' return desc.direction === 'ascending' ? '↑' : '↓' } return ( ) } ``` #### Vue ```vueLoading...{(err) => Error: {err().message}}{(product) => ( )}{product.title}${product.price}{product.category}{product.rating.rate} ({product.rating.count} reviews){(desc) => ( Sorted by {desc().column} ({desc().direction}))}``` #### Svelte ```svelteLoading...Error: {{ list.error.message }}{{ product.title }}${{ product.price }}{{ product.category }}{{ product.rating.rate }} ({{ product.rating.count }} reviews)Sorted by {{ list.sortDescriptor.column }} ({{ list.sortDescriptor.direction }}){#if list().loading}``` ### Dependencies Automatically reload data when dependencies change, such as filter selections or external state. **Example: async-list/dependencies** #### React ```tsx import { useAsyncList } from '@ark-ui/react/collection' import { useState } from 'react' interface User { id: number name: string email: string department: string role: string } export const Dependencies = () => { const [selectedDepartment, setSelectedDepartment] = useStateLoading...{/if} {#if list().error}Error: {list().error.message}{/if}{#each list().items as product}{#if list().sortDescriptor}{/each}{product.title}${product.price}{product.category}{product.rating.rate} ({product.rating.count} reviews)Sorted by {list().sortDescriptor?.column} ({list().sortDescriptor?.direction}){/if}('') const [selectedRole, setSelectedRole] = useState ('') const list = useAsyncList ({ initialItems: mockUsers, // Show all users initially dependencies: [selectedDepartment, selectedRole], async load({ filterText }) { await delay(400) // Simulate network delay let items = mockUsers // Filter by department if (selectedDepartment) { items = items.filter((user) => user.department === selectedDepartment) } // Filter by role if (selectedRole) { items = items.filter((user) => user.role === selectedRole) } // Filter by search text if (filterText) { items = items.filter( (user) => user.name.toLowerCase().includes(filterText.toLowerCase()) || user.email.toLowerCase().includes(filterText.toLowerCase()), ) } return { items } }, }) return ( ) } // Helper function to simulate API delay const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)) const departments = ['Engineering', 'Marketing', 'Sales', 'Support'] const roles = [ 'Senior Developer', 'Marketing Manager', 'Frontend Developer', 'Sales Representative', 'DevOps Engineer', 'Customer Success', 'Content Creator', 'Backend Developer', 'Account Manager', 'Technical Support', 'Brand Manager', 'Full Stack Developer', 'Sales Director', 'Support Manager', 'UI Designer', 'Digital Marketer', 'Mobile Developer', 'Business Development', 'Documentation Specialist', 'Social Media Manager', ] const mockUsers: User[] = [ { id: 1, name: 'Alice Johnson', email: 'alice@example.com', department: 'Engineering', role: 'Senior Developer' }, { id: 2, name: 'Bob Smith', email: 'bob@example.com', department: 'Marketing', role: 'Marketing Manager' }, { id: 3, name: 'Carol Davis', email: 'carol@example.com', department: 'Engineering', role: 'Frontend Developer' }, { id: 4, name: 'David Wilson', email: 'david@example.com', department: 'Sales', role: 'Sales Representative' }, { id: 5, name: 'Eva Brown', email: 'eva@example.com', department: 'Engineering', role: 'DevOps Engineer' }, { id: 6, name: 'Frank Miller', email: 'frank@example.com', department: 'Support', role: 'Customer Success' }, { id: 7, name: 'Grace Lee', email: 'grace@example.com', department: 'Marketing', role: 'Content Creator' }, { id: 8, name: 'Henry Taylor', email: 'henry@example.com', department: 'Engineering', role: 'Backend Developer' }, { id: 9, name: 'Ivy Anderson', email: 'ivy@example.com', department: 'Sales', role: 'Account Manager' }, { id: 10, name: 'Jack Thompson', email: 'jack@example.com', department: 'Support', role: 'Technical Support' }, { id: 11, name: 'Kate Martinez', email: 'kate@example.com', department: 'Marketing', role: 'Brand Manager' }, { id: 12, name: 'Liam Garcia', email: 'liam@example.com', department: 'Engineering', role: 'Full Stack Developer' }, { id: 13, name: 'Mia Rodriguez', email: 'mia@example.com', department: 'Sales', role: 'Sales Director' }, { id: 14, name: 'Noah Lopez', email: 'noah@example.com', department: 'Support', role: 'Support Manager' }, { id: 15, name: 'Olivia White', email: 'olivia@example.com', department: 'Engineering', role: 'UI Designer' }, { id: 16, name: 'Paul Harris', email: 'paul@example.com', department: 'Marketing', role: 'Digital Marketer' }, { id: 17, name: 'Quinn Clark', email: 'quinn@example.com', department: 'Engineering', role: 'Mobile Developer' }, { id: 18, name: 'Ruby Lewis', email: 'ruby@example.com', department: 'Sales', role: 'Business Development' }, { id: 19, name: 'Sam Young', email: 'sam@example.com', department: 'Support', role: 'Documentation Specialist' }, { id: 20, name: 'Tina Walker', email: 'tina@example.com', department: 'Marketing', role: 'Social Media Manager' }, ] ``` #### Solid ```tsx import { useAsyncList } from '@ark-ui/solid/collection' import { createSignal, For } from 'solid-js' interface User { id: number name: string email: string department: string role: string } export const Dependencies = () => { const [selectedDepartment, setSelectedDepartment] = createSignalDependencies Example
list.setFilterText(e.target.value)} /> {list.loading && Loading...}{list.error &&Error: {list.error.message}}Found {list.items.length} users{list.items.map((user) => ({list.items.length === 0 && !list.loading &&))}{user.name}{user.email}{user.department} • {user.role}No users found with current filters}('') const [selectedRole, setSelectedRole] = createSignal ('') const list = useAsyncList ({ initialItems: mockUsers, get dependencies() { return [selectedDepartment(), selectedRole()] }, async load({ filterText }: { filterText?: string }) { await delay(400) let items = mockUsers if (selectedDepartment()) { items = items.filter((user) => user.department === selectedDepartment()) } if (selectedRole()) { items = items.filter((user) => user.role === selectedRole()) } if (filterText) { items = items.filter( (user) => user.name.toLowerCase().includes(filterText.toLowerCase()) || user.email.toLowerCase().includes(filterText.toLowerCase()), ) } return { items } }, }) return ( ) } const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)) const departments = ['Engineering', 'Marketing', 'Sales', 'Support'] const roles = [ 'Senior Developer', 'Marketing Manager', 'Frontend Developer', 'Sales Representative', 'DevOps Engineer', 'Customer Success', 'Content Creator', 'Backend Developer', 'Account Manager', 'Technical Support', 'Brand Manager', 'Full Stack Developer', 'Sales Director', 'Support Manager', 'UI Designer', 'Digital Marketer', 'Mobile Developer', 'Business Development', 'Documentation Specialist', 'Social Media Manager', ] const mockUsers: User[] = [ { id: 1, name: 'Alice Johnson', email: 'alice@example.com', department: 'Engineering', role: 'Senior Developer' }, { id: 2, name: 'Bob Smith', email: 'bob@example.com', department: 'Marketing', role: 'Marketing Manager' }, { id: 3, name: 'Carol Davis', email: 'carol@example.com', department: 'Engineering', role: 'Frontend Developer' }, { id: 4, name: 'David Wilson', email: 'david@example.com', department: 'Sales', role: 'Sales Representative' }, { id: 5, name: 'Eva Brown', email: 'eva@example.com', department: 'Engineering', role: 'DevOps Engineer' }, { id: 6, name: 'Frank Miller', email: 'frank@example.com', department: 'Support', role: 'Customer Success' }, { id: 7, name: 'Grace Lee', email: 'grace@example.com', department: 'Marketing', role: 'Content Creator' }, { id: 8, name: 'Henry Taylor', email: 'henry@example.com', department: 'Engineering', role: 'Backend Developer' }, { id: 9, name: 'Ivy Anderson', email: 'ivy@example.com', department: 'Sales', role: 'Account Manager' }, { id: 10, name: 'Jack Thompson', email: 'jack@example.com', department: 'Support', role: 'Technical Support' }, { id: 11, name: 'Kate Martinez', email: 'kate@example.com', department: 'Marketing', role: 'Brand Manager' }, { id: 12, name: 'Liam Garcia', email: 'liam@example.com', department: 'Engineering', role: 'Full Stack Developer' }, { id: 13, name: 'Mia Rodriguez', email: 'mia@example.com', department: 'Sales', role: 'Sales Director' }, { id: 14, name: 'Noah Lopez', email: 'noah@example.com', department: 'Support', role: 'Support Manager' }, { id: 15, name: 'Olivia White', email: 'olivia@example.com', department: 'Engineering', role: 'UI Designer' }, { id: 16, name: 'Paul Harris', email: 'paul@example.com', department: 'Marketing', role: 'Digital Marketer' }, { id: 17, name: 'Quinn Clark', email: 'quinn@example.com', department: 'Engineering', role: 'Mobile Developer' }, { id: 18, name: 'Ruby Lewis', email: 'ruby@example.com', department: 'Sales', role: 'Business Development' }, { id: 19, name: 'Sam Young', email: 'sam@example.com', department: 'Support', role: 'Documentation Specialist' }, { id: 20, name: 'Tina Walker', email: 'tina@example.com', department: 'Marketing', role: 'Social Media Manager' }, ] ``` #### Vue ```vueDependencies Example
list().setFilterText(e.target.value)} /> {list().loading && Loading...}{list().error &&Error: {list().error.message}}Found {list().items.length} users{list().items.length === 0 && !list().loading &&{(user) => ( )}{user.name}{user.email}{user.department} • {user.role}No users found with current filters}``` #### Svelte ```svelteDependencies Example
Loading...Error: {{ list.error.message }}Found {{ list.items.length }} users{{ user.name }}{{ user.email }}{{ user.department }} • {{ user.role }}No users found with current filters``` ## API Reference ### Props - **load** (`(params: LoadParamslist().setFilterText(e.currentTarget.value)} /> {#if list().loading} Loading... {/if}{#if list().error}Error: {list().error.message}{/if}Found {list().items.length} users{#each list().items as user}{#if list().items.length === 0 && !list().loading}{/each}{user.name}{user.email}{user.department} • {user.role}No users found with current filters{/if}) => Promise ) => Promise `) - Optional function for client-side sorting - **autoReload** (`boolean`, default: `false`) - Whether to automatically reload data on mount - **initialItems** (`T[]`, default: `[]`) - Initial items to display before first load - **dependencies** (`any[]`, default: `[]`) - Values that trigger a reload when changed - **initialFilterText** (`string`, default: `''`) - Initial filter text value - **initialSortDescriptor** (`SortDescriptor | null`) - Initial sort configuration ### Load Parameters The `load` function receives an object with the following properties: - **cursor** (`C | undefined`) - Current cursor for pagination - **filterText** (`string`) - Current filter text - **sortDescriptor** (`SortDescriptor | null`) - Current sort configuration - **signal** (`AbortSignal`) - AbortController signal for request cancellation ### Load Result The `load` function should return an object with: - **items** (`T[]`) - The loaded items - **cursor** (`C | undefined`) - Optional cursor for next page ### Sort Parameters The `sort` function receives an object with: - **items** (`T[]`) - Current items to sort - **descriptor** (`SortDescriptor`) - Sort configuration with `column` and `direction` ### Return Value The hook returns an object with the following properties and methods: #### State Properties - **items** (`T[]`) - Current list of items - **loading** (`boolean`) - Whether a load operation is in progress - **error** (`Error | null`) - Any error from the last operation - **cursor** (`C | undefined`) - Current cursor for pagination - **filterText** (`string`) - Current filter text - **sortDescriptor** (`SortDescriptor | null`) - Current sort configuration #### Methods - **reload** (`() => void`) - Reload data from the beginning - **loadMore** (`() => void`) - Load more items (when cursor is available) - **setFilterText** (`(text: string) => void`) - Set filter text and reload - **sort** (`(descriptor: SortDescriptor) => void`) - Apply sorting #### Types ```tsx interface SortDescriptor { column: string direction: 'ascending' | 'descending' } interface LoadParams { cursor?: C filterText: string sortDescriptor?: SortDescriptor | null signal: AbortSignal } interface LoadResult ) } ``` #### Solid ```tsx import { createListCollection, useListSelection } from '@ark-ui/solid/collection' import { For } from 'solid-js' export const Basic = () => { const collection = createListCollection({ items: ['React', 'Vue', 'Angular'], }) const selection = useListSelection({ collection, }) return ({JSON.stringify(selection.selectedValues)}{collection.items.map((item) => ( ))}) } ``` #### Vue ```vue{JSON.stringify(selection.selectedValues())}{(item) => ( )} ``` #### Svelte ```svelte{{ JSON.stringify(selection.selectedValues.value) }}``` ### Multiple Selection Set `selectionMode` to `multiple` to allow multiple items to be selected. **Example: list-selection/multiple** #### React ```tsx import { createListCollection, useListSelection } from '@ark-ui/react/collection' export const Multiple = () => { const collection = createListCollection({ items: ['React', 'Vue', 'Angular', 'Svelte', 'Solid'], }) const selection = useListSelection({ collection, selectionMode: 'multiple', }) const handleSelectAll = () => { if (selection.isAllSelected()) { selection.clear() } else { selection.setSelectedValues(collection.getValues()) } } return ({JSON.stringify(selection.selectedValues())}{#each collection.items as item (item)} {/each}) } ``` #### Solid ```tsx import { createListCollection, useListSelection } from '@ark-ui/solid/collection' import { For } from 'solid-js' export const Multiple = () => { const collection = createListCollection({ items: ['React', 'Vue', 'Angular', 'Svelte', 'Solid'], }) const selection = useListSelection({ collection, selectionMode: 'multiple', }) const handleSelectAll = () => { if (selection.isAllSelected()) { selection.clear() } else { selection.setSelectedValues(collection.getValues()) } } return ({selection.selectedValues.length} of {collection.items.length} selected{collection.items.map((item) => ( ))}) } ``` #### Vue ```vue{selection.selectedValues().length} of {collection.items.length} selected{(item) => ( )} ``` #### Svelte ```svelte{{ selection.selectedValues.value.length }} of {{ collection.items.length }} selected``` ### Range Selection Here's an example of how to implement range selection that extends the selection from the first selected item to the clicked item. **Example: list-selection/range** #### React ```tsx import { createListCollection, useListSelection } from '@ark-ui/react/collection' export const Range = () => { const collection = createListCollection({ items: [ { value: 'react', label: 'React' }, { value: 'vue', label: 'Vue' }, { value: 'angular', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'solid', label: 'Solid' }, { value: 'preact', label: 'Preact' }, { value: 'qwik', label: 'Qwik' }, { value: 'lit', label: 'Lit' }, ], }) const selection = useListSelection({ collection, selectionMode: 'multiple', }) const handleItemClick = (value: string, event: React.MouseEvent) => { if (event.shiftKey && selection.firstSelectedValue) { // Extend selection from first selected to clicked item selection.extend(selection.firstSelectedValue, value) } else if (event.ctrlKey || event.metaKey) { // Toggle individual item selection.toggle(value) } else { // Replace selection with clicked item selection.replace(value) } } return ({selection.selectedValues().length} of {collection.items.length} selected{#each collection.items as item (item)} {/each}) } ``` #### Solid ```tsx import { createListCollection, useListSelection } from '@ark-ui/solid/collection' import { For } from 'solid-js' export const Range = () => { const items = [ { value: 'react', label: 'React' }, { value: 'vue', label: 'Vue' }, { value: 'angular', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'solid', label: 'Solid' }, { value: 'preact', label: 'Preact' }, { value: 'qwik', label: 'Qwik' }, { value: 'lit', label: 'Lit' }, ] const collection = createListCollection({ items }) const selection = useListSelection({ collection, selectionMode: 'multiple', }) const handleItemClick = (value: string, event: MouseEvent) => { const firstSelectedValue = selection.firstSelectedValue() if (event.shiftKey && firstSelectedValue) { // Extend selection from first selected to clicked item selection.extend(firstSelectedValue, value) } else if (event.ctrlKey || event.metaKey) { // Toggle individual item selection.toggle(value) } else { // Replace selection with clicked item selection.replace(value) } } return ({collection.items.map((item) => ( ))}Instructions:
) } ``` #### Vue ```vueInstructions:
{(item) => ( )} ``` #### Svelte ```svelteInstructions:
{{ item.label }}``` ## API Reference ### Props - **collection** (`ListCollection{#each collection.items as item (item.value)} {/each}Instructions:
`) - The collection to manage selection for - **selectionMode** (`'single' | 'multiple' | 'none'`, default: `'single'`) - The selection mode - **deselectable** (`boolean`, default: `true`) - Whether selected items can be deselected - **initialSelectedValues** (`string[]`, default: `[]`) - Initial selected values - **resetOnCollectionChange** (`boolean`, default: `false`) - Whether to reset selection when collection changes ### Return Value The hook returns an object with the following properties and methods: #### State Properties - **selectedValues** (`string[]`) - Array of currently selected values - **isEmpty** (`boolean`) - Whether no items are selected - **firstSelectedValue** (`string | null`) - The first selected value in collection order - **lastSelectedValue** (`string | null`) - The last selected value in collection order #### Query Methods - **isSelected** (`(value: string | null) => boolean`) - Check if a value is selected - **canSelect** (`(value: string) => boolean`) - Check if a value can be selected - **isAllSelected** (`() => boolean`) - Check if all items are selected - **isSomeSelected** (`() => boolean`) - Check if some items are selected #### Selection Methods - **select** (`(value: string, forceToggle?: boolean) => void`) - Select a value - **deselect** (`(value: string) => void`) - Deselect a value - **toggle** (`(value: string) => void`) - Toggle selection of a value - **replace** (`(value: string | null) => void`) - Replace selection with a single value - **extend** (`(anchorValue: string, targetValue: string) => void`) - Extend selection from anchor to target - **setSelectedValues** (`(values: string[]) => void`) - Set the selected values - **setSelection** (`(values: string[]) => void`) - Set the selection (alias for setSelectedValues) - **clear** (`() => void`) - Clear all selections - **resetSelection** (`() => void`) - Reset selection to initial state # Tree Collection A tree collection is designed to manage hierarchical data structures like file systems, navigation menus, or organization charts. It provides powerful methods for traversing, manipulating, and querying tree structures. ```ts import { createTreeCollection } from '@ark-ui/react/collection' const treeData = { value: 'root', label: 'Root', children: [ { value: 'folder1', label: 'Folder 1', children: [ { value: 'file1', label: 'File 1.txt' }, { value: 'file2', label: 'File 2.txt' }, ], }, { value: 'folder2', label: 'Folder 2', children: [ { value: 'subfolder1', label: 'Subfolder 1', children: [{ value: 'file3', label: 'File 3.txt' }], }, ], }, ], } const tree = createTreeCollection({ rootNode: treeData }) ``` ### Navigation Methods The tree collection provides various methods to navigate through the hierarchical structure. #### Getting First and Last Nodes ```ts const firstNode = tree.getFirstNode() console.log(firstNode?.value) // "folder1" const lastNode = tree.getLastNode() console.log(lastNode?.value) // "folder2" ``` #### Sequential Navigation Navigate to the next or previous node in the tree traversal order: ```ts const nextNode = tree.getNextNode('file1') console.log(nextNode?.value) // "file2" const previousNode = tree.getPreviousNode('file2') console.log(previousNode?.value) // "file1" ``` ### Hierarchical Relationships #### Parent and Children Get parent and descendant nodes: ```ts // Get parent node const parentNode = tree.getParentNode('file1') console.log(parentNode?.value) // "folder1" // Get all ancestor nodes const ancestors = tree.getParentNodes('file3') console.log(ancestors.map((n) => n.value)) // ["folder2", "subfolder1"] // Get all descendant nodes const descendants = tree.getDescendantNodes('folder1') console.log(descendants.map((n) => n.value)) // ["file1", "file2"] // Get descendant values only const descendantValues = tree.getDescendantValues('folder2') console.log(descendantValues) // ["subfolder1", "file3"] ``` #### Sibling Navigation Navigate between sibling nodes: ```ts // Assuming we have the index path of "file1" const indexPath = tree.getIndexPath('file1') // [0, 0] const nextSibling = tree.getNextSibling(indexPath) console.log(nextSibling?.value) // "file2" const previousSibling = tree.getPreviousSibling(indexPath) console.log(previousSibling) // undefined (no previous sibling) // Get all siblings const siblings = tree.getSiblingNodes(indexPath) console.log(siblings.map((n) => n.value)) // ["file1", "file2"] ``` ### Index Path Operations Work with index paths to identify node positions: ```ts // Get index path for a value const indexPath = tree.getIndexPath('file3') console.log(indexPath) // [1, 0, 0] // Get value from index path const value = tree.getValue([1, 0, 0]) console.log(value) // "file3" // Get full value path (all ancestors + node) const valuePath = tree.getValuePath([1, 0, 0]) console.log(valuePath) // ["folder2", "subfolder1", "file3"] // Get node at specific index path const node = tree.at([1, 0]) console.log(node?.value) // "subfolder1" ``` ### Tree Queries #### Branch and Leaf Detection ```ts // Check if a node is a branch (has children) const folder1Node = tree.findNode('folder1') const isBranch = tree.isBranchNode(folder1Node!) console.log(isBranch) // true // Get all branch values const branchValues = tree.getBranchValues() console.log(branchValues) // ["folder1", "folder2", "subfolder1"] ``` #### Tree Traversal Visit all nodes with custom logic: ```ts tree.visit({ onEnter: (node, indexPath) => { console.log(`Visiting: ${node.value} at depth ${indexPath.length}`) // Skip certain branches if (node.value === 'folder2') { return 'skip' // Skip this branch and its children } }, }) ``` #### Filtering Create a new tree with filtered nodes: ```ts // Keep only nodes that match criteria const filteredTree = tree.filter((node, indexPath) => { return node.value.includes('file') // Only keep files }) console.log(filteredTree.getValues()) // ["file1", "file2", "file3"] ``` ### Tree Manipulation #### Adding Nodes ```ts const newFile = { value: 'newfile', label: 'New File.txt' } // Insert after a specific node const indexPath = tree.getIndexPath('file1') const updatedTree = tree.insertAfter(indexPath!, [newFile]) // Insert before a specific node const updatedTree2 = tree.insertBefore(indexPath!, [newFile]) ``` #### Removing Nodes ```ts const indexPath = tree.getIndexPath('file2') const updatedTree = tree.remove([indexPath!]) console.log(updatedTree.getValues()) // file2 is removed ``` #### Moving Nodes ```ts const fromIndexPaths = [tree.getIndexPath('file1')!] const toIndexPath = tree.getIndexPath('folder2')! const updatedTree = tree.move(fromIndexPaths, toIndexPath) // file1 is now moved under folder2 ``` #### Replacing Nodes ```ts const indexPath = tree.getIndexPath('file1')! const newNode = { value: 'replacedfile', label: 'Replaced File.txt' } const updatedTree = tree.replace(indexPath, newNode) ``` ### Utility Methods #### Flattening Convert the tree to a flat structure: ```ts const flatNodes = tree.flatten() console.log(flatNodes.map((n) => ({ value: n.value, depth: n._indexPath.length }))) // [{ value: "folder1", depth: 1 }, { value: "file1", depth: 2 }, ...] ``` #### Getting All Values ```ts const allValues = tree.getValues() console.log(allValues) // ["folder1", "file1", "file2", "folder2", "subfolder1", "file3"] ``` #### Depth Calculation ```ts const depth = tree.getDepth('file3') console.log(depth) // 3 (root -> folder2 -> subfolder1 -> file3) ``` ### Working with Custom Node Types You can customize how the tree collection interprets your data: ```ts interface CustomNode { id: string name: string items?: CustomNode[] isDisabled?: boolean } const customTree = createTreeCollection ({ rootNode: { id: 'root', name: 'Root', items: [ { id: '1', name: 'Item 1', isDisabled: false }, { id: '2', name: 'Item 2', isDisabled: true }, ], }, nodeToValue: (node) => node.id, nodeToString: (node) => node.name, nodeToChildren: (node) => node.items, isNodeDisabled: (node) => node.isDisabled ?? false, }) ``` ### Creating Trees from File Paths Create a tree structure from file paths: ```ts import { createFileTreeCollection } from '@ark-ui/react/collection' const paths = ['src/components/Button.tsx', 'src/components/Input.tsx', 'src/utils/helpers.ts', 'docs/README.md'] const fileTree = createFileTreeCollection(paths) console.log(fileTree.getBranchValues()) // ["src", "components", "utils", "docs"] ``` > **Good to know**: Tree collections are immutable - all modification methods return a new tree instance rather than > modifying the original. # COMPONENTS --- # Accordion ## Features - Full keyboard navigation - Supports horizontal and vertical orientation - Right-to-Left (RTL) support - Single or multiple item expansion - Controlled and uncontrolled modes - Collapse each accordion item ## Anatomy To set up the accordion correctly, it's essential to understand its anatomy and the naming of its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples ### Default Expanded State Set the `defaultValue` prop to specify which item should be expanded by default. **Example: basic** #### React ```tsx import { Accordion } from '@ark-ui/react/accordion' import { ChevronDownIcon } from 'lucide-react' export const Basic = () => { return ( {['React', 'Solid', 'Vue', 'Svelte'].map((item) => ( ) } ``` #### Solid ```tsx import { Accordion } from '@ark-ui/solid/accordion' import { ChevronDownIcon } from 'lucide-solid' import { Index } from 'solid-js' export const Basic = () => { return (What is {item}? {item} is a JavaScript library for building user interfaces. {(item) => ( What is {item()}? {item()} is a JavaScript library for building user interfaces. What is {{ item }}? {{ item }} is a JavaScript library for building user interfaces. {#each items as item (item)} ``` ### Collapsible Use the `collapsible` prop to allow the user to collapse all panels. **Example: collapsible** #### React ```tsx import { Accordion } from '@ark-ui/react/accordion' import { ChevronDownIcon } from 'lucide-react' export const Collapsible = () => { return (What is {item}? {item} is a JavaScript library for building user interfaces. {['React', 'Solid', 'Vue', 'Svelte'].map((item) => ( ) } ``` #### Solid ```tsx import { Accordion } from '@ark-ui/solid/accordion' import { ChevronDownIcon } from 'lucide-solid' import { Index } from 'solid-js' export const Collapsible = () => { return ({item} {item} is a JavaScript library for building user interfaces. {(item) => ( What is {item()}? {item()} is a JavaScript library for building user interfaces. What is {{ item }}? {{ item }} is a JavaScript library for building user interfaces. {#each ['React', 'Solid', 'Vue', 'Svelte'] as item (item)} ``` ### Multiple Panels Use the `multiple` prop to allow multiple panels to be expanded simultaneously. **Example: multiple** #### React ```tsx import { Accordion } from '@ark-ui/react/accordion' import { ChevronDownIcon } from 'lucide-react' export const Multiple = () => { return (What is {item}? {item} is a JavaScript library for building user interfaces. {['React', 'Solid', 'Vue', 'Svelte'].map((item) => ( ) } ``` #### Solid ```tsx import { Accordion } from '@ark-ui/solid/accordion' import { ChevronDownIcon } from 'lucide-solid' import { Index } from 'solid-js' export const Multiple = () => { return ({item} {item} is a JavaScript library for building user interfaces. {(item) => ( What is {item()}? {item()} is a JavaScript library for building user interfaces. What is {{ item }}? {{ item }} is a JavaScript library for building user interfaces. {#each ['React', 'Solid', 'Vue', 'Svelte'] as item (item)} ``` ### Horizontal Orientation By default, the Accordion is oriented vertically. Use the `orientation` prop to switch to a horizontal layout. **Example: horizontal** #### React ```tsx import { Accordion } from '@ark-ui/react/accordion' import { ChevronDownIcon } from 'lucide-react' export const Horizontal = () => { return (What is {item}? {item} is a JavaScript library for building user interfaces. {['React', 'Solid', 'Vue', 'Svelte'].map((item) => ( ) } ``` #### Solid ```tsx import { Accordion } from '@ark-ui/solid/accordion' import { ChevronDownIcon } from 'lucide-solid' import { Index } from 'solid-js' export const Horizontal = () => { return (What is {item}? {item} is a JavaScript library for building user interfaces. {(item) => ( What is {item()}? {item()} is a JavaScript library for building user interfaces. What is {{ item }}? {{ item }} is a JavaScript library for building user interfaces. ``` ### Using the Root Provider The `RootProvider` component provides a context for the accordion. It accepts the value of the `useAccordion` hook. You can leverage it to access the component state and methods from outside the accordion. **Example: root-provider** #### React ```tsx import { Accordion, useAccordion } from '@ark-ui/react/accordion' import { ChevronDownIcon } from 'lucide-react' export const RootProvider = () => { const accordion = useAccordion({ multiple: true, defaultValue: ['React'], }) return ( <>{#each ['React', 'Solid', 'Vue', 'Svelte'] as item (item)} What is {item}? {item} is a JavaScript library for building user interfaces. {['React', 'Solid', 'Vue', 'Svelte'].map((item) => ( ) } ``` #### Solid ```tsx import { Accordion, useAccordion } from '@ark-ui/solid/accordion' import { ChevronDownIcon } from 'lucide-solid' import { Index } from 'solid-js' export const RootProvider = () => { const accordion = useAccordion({ multiple: true, defaultValue: ['React'], }) return ( <>What is {item}? {item} is a JavaScript library for building user interfaces. {(item) => ( What is {item()}? {item()} is a JavaScript library for building user interfaces. What is {{ item }}? {{ item }} is a JavaScript library for building user interfaces. ``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ### Accessing context Use the `Accordion.Context` component or `useAccordionContext` hook to access the state of an accordion. It exposes the following properties: - `focusedValue`: The value of the focused accordion item. - `value`: The value of the selected accordion items. - `setValue`: A method to set the selected accordion items. **Example: context** #### React ```tsx import { Accordion } from '@ark-ui/react/accordion' import { ChevronDownIcon } from 'lucide-react' export const Context = () => { return (Open items: {JSON.stringify(accordion().value)}{#each ['React', 'Solid', 'Vue', 'Svelte'] as item (item)} What is {item}? {item} is a JavaScript library for building user interfaces. {(context) => ( {['React', 'Solid', 'Vue', 'Svelte'].map((item) => (Selected items: {context.value.join(', ')} Focused item: {context.focusedValue})}What is {item}? {item} is a JavaScript library for building user interfaces. {(context) => ( Selected items: {context().value.join(', ')} Focused item: {context().focusedValue})}{(item) => ( What is {item()}? {item()} is a JavaScript library for building user interfaces. What is {{ item }}? {{ item }} is a JavaScript library for building user interfaces. {#snippet render(context)} {#each ['React', 'Solid', 'Vue', 'Svelte'] as item}Selected items: {context().value.join(', ')} Focused item: {context().focusedValue}{/snippet}What is {item}? {item} is a JavaScript library for building user interfaces. {['React', 'Solid', 'Vue', 'Svelte'].map((item) => ( ) } ``` #### Solid ```tsx import { Accordion } from '@ark-ui/solid/accordion' import { ChevronDownIcon } from 'lucide-solid' import { Index } from 'solid-js' export const ItemContext = () => { return (What is {item}? {(context) => ( Expanded: {String(context.expanded)} Focused: {String(context.focused)} Disabled: {String(context.disabled)})}{item} is a JavaScript library for building user interfaces. {(item) => ( What is {item()}? {(context) => ( Expanded: {String(context().expanded)} Focused: {String(context().focused)} Disabled: {String(context().disabled)})}{item()} is a JavaScript library for building user interfaces. What is {{ item }}? Expanded: {{ context.expanded }} Focused: {{ context.focused }} Disabled: {{ context.disabled }}{{ item }} is a JavaScript library for building user interfaces. {#each ['React', 'Solid', 'Vue', 'Svelte'] as item} ``` ## Guides ### Animate Content Size Use the `--height` and/or `--width` CSS variables to animate the size of the content when it expands or closes: ```css @keyframes slideDown { from { opacity: 0.01; height: 0; } to { opacity: 1; height: var(--height); } } @keyframes slideUp { from { opacity: 1; height: var(--height); } to { opacity: 0.01; height: 0; } } [data-scope='accordion'][data-part='item-content'][data-state='open'] { animation: slideDown 250ms ease-in-out; } [data-scope='accordion'][data-part='item-content'][data-state='closed'] { animation: slideUp 200ms ease-in-out; } ``` ## API Reference ### Props **Component API Reference** #### React **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `collapsible` | `boolean` | No | Whether an accordion item can be closed after it has been expanded. | | `defaultValue` | `string[]` | No | The initial value of the expanded accordion items. Use when you don't need to control the value of the accordion. | | `disabled` | `boolean` | No | Whether the accordion items are disabled | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string item: (value: string) => string itemContent: (value: string) => string itemTrigger: (value: string) => string }>` | No | The ids of the elements in the accordion. Useful for composition. | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `multiple` | `boolean` | No | Whether multiple accordion items can be expanded at the same time. | | `onFocusChange` | `(details: FocusChangeDetails) => void` | No | The callback fired when the focused accordion item changes. | | `onValueChange` | `(details: ValueChangeDetails) => void` | No | The callback fired when the state of expanded/collapsed accordion items changes. | | `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the accordion items. | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | | `value` | `string[]` | No | The controlled value of the expanded accordion items. | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | accordion | | `[data-part]` | root | | `[data-orientation]` | The orientation of the accordion | **ItemContent Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemContent Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | accordion | | `[data-part]` | item-content | | `[data-state]` | "open" | "closed" | | `[data-disabled]` | Present when disabled | | `[data-focus]` | Present when focused | | `[data-orientation]` | The orientation of the item | **ItemIndicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemIndicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | accordion | | `[data-part]` | item-indicator | | `[data-state]` | "open" | "closed" | | `[data-disabled]` | Present when disabled | | `[data-focus]` | Present when focused | | `[data-orientation]` | The orientation of the item | **Item Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `string` | Yes | The value of the accordion item. | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `disabled` | `boolean` | No | Whether the accordion item is disabled. | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | accordion | | `[data-part]` | item | | `[data-state]` | "open" | "closed" | | `[data-focus]` | Present when focused | | `[data-disabled]` | Present when disabled | | `[data-orientation]` | The orientation of the item | **ItemTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | accordion | | `[data-part]` | item-trigger | | `[data-orientation]` | The orientation of the item | | `[data-state]` | "open" | "closed" | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseAccordionReturn` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | #### Solid **Root 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. | | `collapsible` | `boolean` | No | Whether an accordion item can be closed after it has been expanded. | | `defaultValue` | `string[]` | No | The initial value of the expanded accordion items. Use when you don't need to control the value of the accordion. | | `disabled` | `boolean` | No | Whether the accordion items are disabled | | `ids` | `Partial<{ root: string item: (value: string) => string itemContent: (value: string) => string itemTrigger: (value: string) => string }>` | No | The ids of the elements in the accordion. Useful for composition. | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `multiple` | `boolean` | No | Whether multiple accordion items can be expanded at the same time. | | `onFocusChange` | `(details: FocusChangeDetails) => void` | No | The callback fired when the focused accordion item changes. | | `onValueChange` | `(details: ValueChangeDetails) => void` | No | The callback fired when the state of expanded/collapsed accordion items changes. | | `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the accordion items. | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | | `value` | `string[]` | No | The controlled value of the expanded accordion items. | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | accordion | | `[data-part]` | root | | `[data-orientation]` | The orientation of the accordion | **ItemContent 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. | **ItemContent Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | accordion | | `[data-part]` | item-content | | `[data-state]` | "open" | "closed" | | `[data-disabled]` | Present when disabled | | `[data-focus]` | Present when focused | | `[data-orientation]` | The orientation of the item | **ItemIndicator 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. | **ItemIndicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | accordion | | `[data-part]` | item-indicator | | `[data-state]` | "open" | "closed" | | `[data-disabled]` | Present when disabled | | `[data-focus]` | Present when focused | | `[data-orientation]` | The orientation of the item | **Item Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `string` | Yes | The value of the accordion item. | | `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 accordion item is disabled. | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | accordion | | `[data-part]` | item | | `[data-state]` | "open" | "closed" | | `[data-focus]` | Present when focused | | `[data-disabled]` | Present when disabled | | `[data-orientation]` | The orientation of the item | **ItemTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | accordion | | `[data-part]` | item-trigger | | `[data-orientation]` | The orientation of the item | | `[data-state]` | "open" | "closed" | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseAccordionReturn` | Yes | | | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | #### Vue **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `collapsible` | `boolean` | No | Whether an accordion item can be closed after it has been expanded. | | `defaultValue` | `string[]` | No | The initial value of the expanded accordion items. Use when you don't need to control the value of the accordion. | | `disabled` | `boolean` | No | Whether the accordion items are disabled | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string item(value: string): string itemContent(value: string): string itemTrigger(value: string): string }>` | No | The ids of the elements in the accordion. Useful for composition. | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `modelValue` | `string[]` | No | The v-model value of the accordion | | `multiple` | `boolean` | No | Whether multiple accordion items can be expanded at the same time. | | `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the accordion items. | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | accordion | | `[data-part]` | root | | `[data-orientation]` | The orientation of the accordion | **ItemContent Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemContent Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | accordion | | `[data-part]` | item-content | | `[data-state]` | "open" | "closed" | | `[data-disabled]` | Present when disabled | | `[data-focus]` | Present when focused | | `[data-orientation]` | The orientation of the item | **ItemIndicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemIndicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | accordion | | `[data-part]` | item-indicator | | `[data-state]` | "open" | "closed" | | `[data-disabled]` | Present when disabled | | `[data-focus]` | Present when focused | | `[data-orientation]` | The orientation of the item | **Item Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `string` | Yes | The value of the accordion item. | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `disabled` | `boolean` | No | Whether the accordion item is disabled. | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | accordion | | `[data-part]` | item | | `[data-state]` | "open" | "closed" | | `[data-focus]` | Present when focused | | `[data-disabled]` | Present when disabled | | `[data-orientation]` | The orientation of the item | **ItemTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | accordion | | `[data-part]` | item-trigger | | `[data-orientation]` | The orientation of the item | | `[data-state]` | "open" | "closed" | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `AccordionApiWhat is {item}? {#snippet render(context)} Expanded: {context().expanded} Focused: {context().focused} Disabled: {context().disabled}{/snippet}{item} is a JavaScript library for building user interfaces. ` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | #### Svelte **Root 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. | | `collapsible` | `boolean` | No | Whether an accordion item can be closed after it has been expanded. | | `defaultValue` | `string[]` | No | The initial value of the expanded accordion items. Use when you don't need to control the value of the accordion. | | `disabled` | `boolean` | No | Whether the accordion items are disabled | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string item: (value: string) => string itemContent: (value: string) => string itemTrigger: (value: string) => string }>` | No | The ids of the elements in the accordion. Useful for composition. | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `multiple` | `boolean` | No | Whether multiple accordion items can be expanded at the same time. | | `onFocusChange` | `(details: FocusChangeDetails) => void` | No | The callback fired when the focused accordion item changes. | | `onValueChange` | `(details: ValueChangeDetails) => void` | No | The callback fired when the state of expanded/collapsed accordion items changes. | | `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the accordion items. | | `ref` | `Element` | No | | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | | `value` | `string[]` | No | The controlled value of the expanded accordion items. | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | accordion | | `[data-part]` | root | | `[data-orientation]` | The orientation of the accordion | **Context Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `render` | `Snippet<[UseAccordionContext]>` | Yes | | **ItemContent 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. | | `ref` | `Element` | No | | **ItemContent Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | accordion | | `[data-part]` | item-content | | `[data-state]` | "open" | "closed" | | `[data-disabled]` | Present when disabled | | `[data-focus]` | Present when focused | | `[data-orientation]` | The orientation of the item | **ItemContext Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `render` | `Snippet<[UseAccordionItemContext]>` | Yes | | **ItemIndicator 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. | | `ref` | `Element` | No | | **ItemIndicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | accordion | | `[data-part]` | item-indicator | | `[data-state]` | "open" | "closed" | | `[data-disabled]` | Present when disabled | | `[data-focus]` | Present when focused | | `[data-orientation]` | The orientation of the item | **Item Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `string` | Yes | The value of the accordion item. | | `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 accordion item is disabled. | | `ref` | `Element` | No | | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | accordion | | `[data-part]` | item | | `[data-state]` | "open" | "closed" | | `[data-focus]` | Present when focused | | `[data-disabled]` | Present when disabled | | `[data-orientation]` | The orientation of the item | **ItemTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **ItemTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | accordion | | `[data-part]` | item-trigger | | `[data-orientation]` | The orientation of the item | | `[data-state]` | "open" | "closed" | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseAccordionReturn` | Yes | | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `ref` | `Element` | No | | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | ### Context These are the properties available when using `Accordion.Context`, `useAccordionContext` hook or `useAccordion` hook. **API:** | Property | Type | Description | |----------|------|-------------| | `focusedValue` | `string` | The value of the focused accordion item. | | `value` | `string[]` | The value of the accordion | | `setValue` | `(value: string[]) => void` | Sets the value of the accordion | | `getItemState` | `(props: ItemProps) => ItemState` | Returns the state of an accordion item. | ## Accessibility This component complies with the [Accordion WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/). ### Keyboard Support **`Space`** Description: When focus is on an trigger of a collapsed item, the item is expanded **`Enter`** Description: When focus is on an trigger of a collapsed section, expands the section. **`Tab`** Description: Moves focus to the next focusable element **`Shift + Tab`** Description: Moves focus to the previous focusable element **`ArrowDown`** Description: Moves focus to the next trigger **`ArrowUp`** Description: Moves focus to the previous trigger. **`Home`** Description: When focus is on an trigger, moves focus to the first trigger. **`End`** Description: When focus is on an trigger, moves focus to the last trigger. # Angle Slider ## Examples ### Basic Here's a basic example of the Angle Slider component. **Example: basic** #### React ```tsx import { AngleSlider } from '@ark-ui/react/angle-slider' export const Basic = () => { return ( Wind direction {[0, 45, 90, 135, 180, 225, 270, 315].map((value, i) => ( ))} Angle {(value) => {value}° }Wind direction Wind direction {#each [0, 45, 90, 135, 180, 225, 270, 315] as value} {/each} setAngle(value)}> ) } ``` #### Solid ```tsx import { AngleSlider } from '@ark-ui/solid/angle-slider' import { For, createSignal } from 'solid-js' export const Controlled = () => { const [value, setValue] = createSignal(0) return (Temperature {[0, 45, 90, 135, 180, 225, 270, 315].map((value, i) => ( ))} {angle} ºC setValue(e.value)}> ) } ``` #### Vue ```vueAngle {(value) => {value}° }Temperature {{ angle }} ºC Temperature {#each [0, 45, 90, 135, 180, 225, 270, 315] as value} {/each} {value} ºC Wind direction (15 step) {[0, 45, 90, 135, 180, 225, 270, 315].map((value, i) => ( ))} Angle {(value) => } Angle Wind direction (15 step) {#each [0, 45, 90, 135, 180, 225, 270, 315] as value} {/each} ` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Thumb Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Thumb Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | angle-slider | | `[data-part]` | thumb | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **ValueText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | #### Svelte **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `aria-label` | `string` | No | The accessible label for the slider thumb. | | `aria-labelledby` | `string` | No | The id of the element that labels the slider thumb. | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `defaultValue` | `number` | No | The initial value of the slider. Use when you don't need to control the value of the slider. | | `disabled` | `boolean` | No | Whether the slider is disabled. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string thumb: string hiddenInput: string control: string valueText: string label: string }>` | No | The ids of the elements in the machine. Useful for composition. | | `invalid` | `boolean` | No | Whether the slider is invalid. | | `name` | `string` | No | The name of the slider. Useful for form submission. | | `onValueChange` | `(details: ValueChangeDetails) => void` | No | The callback function for when the value changes. | | `onValueChangeEnd` | `(details: ValueChangeDetails) => void` | No | The callback function for when the value changes ends. | | `readOnly` | `boolean` | No | Whether the slider is read-only. | | `ref` | `Element` | No | | | `step` | `number` | No | The step value for the slider. | | `value` | `number` | No | The value of the slider. | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | angle-slider | | `[data-part]` | root | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **Context Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `render` | `Snippet<[UseAngleSliderContext]>` | Yes | | **Control 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. | | `ref` | `Element` | No | | **Control Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | angle-slider | | `[data-part]` | control | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **HiddenInput Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'input'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'label'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | angle-slider | | `[data-part]` | label | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **MarkerGroup 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. | | `ref` | `Element` | No | | **Marker Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `number` | Yes | The value of the marker | | `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Marker Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | angle-slider | | `[data-part]` | marker | | `[data-value]` | The value of the item | | `[data-state]` | | | `[data-disabled]` | Present when disabled | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseAngleSliderReturn` | Yes | | | `ref` | `Element` | No | | **Thumb 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. | | `ref` | `Element` | No | | **Thumb Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | angle-slider | | `[data-part]` | thumb | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **ValueText 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. | | `ref` | `Element` | No | | ### Context These are the properties available when using `AngleSlider.Context`, `useAngleSliderContext` hook or `useAngleSlider` hook. **API:** | Property | Type | Description | |----------|------|-------------| | `value` | `number` | The current value of the angle slider | | `valueAsDegree` | `string` | The current value as a degree string | | `setValue` | `(value: number) => void` | Sets the value of the angle slider | | `dragging` | `boolean` | Whether the slider is being dragged. | # Avatar ## Anatomy To set up the avatar correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples Learn how to use the `Avatar` component in your project. Let's take a look at the most basic example: **Example: basic** #### React ```tsx import { Avatar } from '@ark-ui/react/avatar' export const Basic = () => ( PA PA PA PA PA PA PA PA PA PA PA PA ) } const Demo = () => { return (
JD ` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | #### Svelte **Root 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. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string; image: string; fallback: string }>` | No | The ids of the elements in the avatar. Useful for composition. | | `onStatusChange` | `(details: StatusChangeDetails) => void` | No | Functional called when the image loading status changes. | | `ref` | `Element` | No | | **Fallback Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Fallback Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | avatar | | `[data-part]` | fallback | | `[data-state]` | "hidden" | "visible" | **Image Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'img'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Image Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | avatar | | `[data-part]` | image | | `[data-state]` | "visible" | "hidden" | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseAvatarReturn` | Yes | | | `ref` | `Element` | No | | ### Context These are the properties available when using `Avatar.Context`, `useAvatarContext` hook or `useAvatar` hook. **API:** | Property | Type | Description | |----------|------|-------------| | `loaded` | `boolean` | Whether the image is loaded. | | `setSrc` | `(src: string) => void` | Function to set new src. | | `setLoaded` | `VoidFunction` | Function to set loaded state. | | `setError` | `VoidFunction` | Function to set error state. | # Carousel ## Features - Native CSS Scroll Snap integration for smooth, performant animations - Flexible orientation support (horizontal and vertical layouts) - Customizable slide alignment (start, center, or end positions) - Multi-slide display capabilities for complex layouts - Automatic playback with configurable looping behavior - Adjustable slide spacing and gap controls ## Anatomy To set up the carousel correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples Learn how to use the `Carousel` component in your project. Let's take a look at the most basic example: **Example: basic** #### React ```tsx import { Carousel } from '@ark-ui/react/carousel' export const Basic = () => { const images = Array.from({ length: 5 }, (_, i) => `https://picsum.photos/seed/${i + 1}/500/300`) return ( Previous Next {images.map((_, index) => ( ))} {images.map((image, index) => ( Previous Next {(_, index) => } {(image, index) => ( Previous Next Previous Next {#each images as _, index} {/each} {#each images as image, index} setPage(e.page)}> ) } ``` #### Solid ```tsx import { Carousel } from '@ark-ui/solid/carousel' import { Index, createSignal } from 'solid-js' const images = Array.from({ length: 5 }, (_, i) => `https://picsum.photos/seed/${i + 1}/500/300`) export const Controlled = () => { const [page, setPage] = createSignal(0) return (Previous Next {images.map((_, index) => ( ))} {images.map((image, index) => ( setPage(details.page)}> ) } ``` #### Vue ```vuePrevious Next {(_, index) => } {(image, index) => ( Previous Next Current page: {{ page }}
``` #### Svelte ```svelte``` ### Root Provider Use the `useCarousel` hook to create the carousel store and pass it to the `Carousel.RootProvider` component. This allows you to have maximum control over the carousel programmatically. **Example: root-provider** #### React ```tsx import { Carousel, useCarousel } from '@ark-ui/react/carousel' const images = Array.from({ length: 5 }, (_, i) => `https://picsum.photos/seed/${i + 1}/500/300`) export const RootProvider = () => { const carousel = useCarousel({ slideCount: images.length }) return ( <>Current page: {page}Previous Next {#each images as _, index} {/each} {#each images as image, index} Previous Next {images.map((_, index) => ( ))} {images.map((image, index) => ( Previous Next {(_, index) => } {(image, index) => ( Previous Next ``` > If you're using the `Carousel.RootProvider` component, you don't need to use the `Carousel.Root` component. ### Autoplay Pass the `autoplay` and `loop` props to `Carousel.Root` to make the carousel play automatically. > **Note:** Adding `loop` ensures the carousel keeps going after the last slide. **Example: autoplay** #### React ```tsx import { Carousel } from '@ark-ui/react/carousel' const images = Array.from({ length: 5 }, (_, i) => `https://picsum.photos/seed/${i + 1}/500/300`) export const Autoplay = () => { return (Current page: {carousel().page}Previous Next {#each images as _, index} {/each} {#each images as image, index} Pause {images.map((_, index) => ( ))} {images.map((image, index) => ( Pause {(_, index) => } {(image, index) => ( Pause Previous {#snippet fallback()}Play{/snippet} Pause Next {#each images as _, index} {/each} {#each images as image, index} {({ isPlaying }) => `Autoplay is: ${isPlaying ? 'playing' : 'paused'}`} {(api) => ( api.pause()} onPointerLeave={() => api.play()}> {images.map((image, index) => ( )}{images.map((_, index) => ( ))} {(carousel) => `Autoplay is: ${carousel().isPlaying ? 'playing' : 'paused'}`} {(api) => ( api().pause()} onPointerLeave={() => api().play()}> )}{(image, index) => ( {(_, index) => } Autoplay is: {{ context.isPlaying ? 'playing' : 'paused' }} {#snippet render(api)} Autoplay is: {api().isPlaying ? 'playing' : 'paused'} {/snippet} {#snippet render(api)} api().pause()} onpointerleave={() => api().play()}> {#each images as image, index} {/snippet}{#each images as _, index} {/each} Previous Next {images.map((image, index) => ( {(api) => ( {images.map((image, index) => ( )}Previous Next {(image, index) => ( {(api) => ( {(image, index) => ( Previous Next Previous Next {#each images as image, index} {#snippet render(api)} {#each images as image, index} {/snippet}Previous Next {images.map((_, index) => ( ))} {images.map((image, index) => ( Previous Next {(_, index) => } {(image, index) => ( Previous Next Previous Next {#each images as _, index} {/each} {#each images as image, index} setPage(details.page)}> Previous Next {slides.map((_, index) => ( ))} {slides.map((slide, index) => ( setPage(details.page)}> Previous Next {(_, index) => } {(slide, index) => ( Previous Next Slide {{ slide }}``` ### Scroll to Slide Use `Carousel.Context` to access the carousel API and call `api.scrollToIndex(index)` to programmatically navigate to a specific slide. This is useful for creating custom navigation or jump-to-slide functionality. **Example: scroll-to** #### React ```tsx import { Carousel } from '@ark-ui/react/carousel' export const ScrollTo = () => { return (Previous Next {#each slides as _, index} {/each} {#each slides as slide, index} {(api) => } {Array.from({ length: 5 }, (_, index) => ( Previous Next {Array.from({ length: 5 }, (_, index) => ( ))} {(api) => } {(_, index) => ( Previous Next {(_, index) => } Previous Next {#snippet render(carousel)} {/snippet} {#each Array.from({ length: 5 }) as _, index} Previous Next {#each Array.from({ length: 5 }) as _, index} {/each} Previous Next {slides.map((_, index) => ( {(api) => ( {api.pageSnapPoints.map((_, index) => ( )}))} Previous Next {(_, index) => ( {(api) => ( {(_, index) => } Previous Next Slide {{ idx + 1 }}Previous Next {#each slides as _, index} {#snippet render(api)} {#each api().pageSnapPoints as _, index} {/snippet}{/each} | ReactPortal | Promise<...>` | No | The content to render when autoplay is paused. | | `playing` | `string | number | bigint | boolean | ReactElement | ReactPortal | Promise<...>` | No | The content to render when autoplay is playing. | **AutoplayTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **AutoplayTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | autoplay-trigger | | `[data-orientation]` | The orientation of the autoplaytrigger | | `[data-pressed]` | Present when pressed | **Control Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Control Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | control | | `[data-orientation]` | The orientation of the control | **IndicatorGroup Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **IndicatorGroup Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | indicator-group | | `[data-orientation]` | The orientation of the indicatorgroup | **Indicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `index` | `number` | Yes | The index of the indicator. | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `readOnly` | `boolean` | No | Whether the indicator is read only. | **Indicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | indicator | | `[data-orientation]` | The orientation of the indicator | | `[data-index]` | The index of the item | | `[data-readonly]` | Present when read-only | | `[data-current]` | Present when current | **ItemGroup Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemGroup Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | item-group | | `[data-orientation]` | The orientation of the item | | `[data-dragging]` | Present when in the dragging state | **Item Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `index` | `number` | Yes | The index of the item. | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `snapAlign` | `'center' | 'start' | 'end'` | No | The snap alignment of the item. | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | item | | `[data-index]` | The index of the item | | `[data-inview]` | Present when in viewport | | `[data-orientation]` | The orientation of the item | **NextTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **NextTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | next-trigger | | `[data-orientation]` | The orientation of the nexttrigger | **PrevTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **PrevTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | prev-trigger | | `[data-orientation]` | The orientation of the prevtrigger | **ProgressText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseCarouselReturn` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | #### Solid **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `slideCount` | `number` | Yes | The total number of slides. Useful for SSR to render the initial ating the snap points. | | `allowMouseDrag` | `boolean` | No | Whether to allow scrolling via dragging with mouse | | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `autoplay` | `boolean | { delay: number }` | No | Whether to scroll automatically. The default delay is 4000ms. | | `defaultPage` | `number` | No | The initial page to scroll to when rendered. Use when you don't need to control the page of the carousel. | | `ids` | `Partial<{ root: string item: (index: number) => string itemGroup: string nextTrigger: string prevTrigger: string indicatorGroup: string indicator: (index: number) => string }>` | No | The ids of the elements in the carousel. Useful for composition. | | `inViewThreshold` | `number | number[]` | No | The threshold for determining if an item is in view. | | `loop` | `boolean` | No | Whether the carousel should loop around. | | `onAutoplayStatusChange` | `(details: AutoplayStatusDetails) => void` | No | Function called when the autoplay status changes. | | `onDragStatusChange` | `(details: DragStatusDetails) => void` | No | Function called when the drag status changes. | | `onPageChange` | `(details: PageChangeDetails) => void` | No | Function called when the page changes. | | `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the element. | | `padding` | `string` | No | Defines the extra space added around the scrollable area, enabling nearby items to remain partially in view. | | `page` | `number` | No | The controlled page of the carousel. | | `slidesPerMove` | `number | 'auto'` | No | The number of slides to scroll at a time. When set to `auto`, the number of slides to scroll is determined by the `slidesPerPage` property. | | `slidesPerPage` | `number` | No | The number of slides to show at a time. | | `snapType` | `'proximity' | 'mandatory'` | No | The snap type of the item. | | `spacing` | `string` | No | The amount of space between items. | | `translations` | `IntlTranslations` | No | The localized messages to use. | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | root | | `[data-orientation]` | The orientation of the carousel | **AutoplayTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **AutoplayTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | autoplay-trigger | | `[data-orientation]` | The orientation of the autoplaytrigger | | `[data-pressed]` | Present when pressed | **Control 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. | **Control Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | control | | `[data-orientation]` | The orientation of the control | **IndicatorGroup 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. | **IndicatorGroup Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | indicator-group | | `[data-orientation]` | The orientation of the indicatorgroup | **Indicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `index` | `number` | Yes | The index of the indicator. | | `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `readOnly` | `boolean` | No | Whether the indicator is read only. | **Indicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | indicator | | `[data-orientation]` | The orientation of the indicator | | `[data-index]` | The index of the item | | `[data-readonly]` | Present when read-only | | `[data-current]` | Present when current | **ItemGroup 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. | **ItemGroup Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | item-group | | `[data-orientation]` | The orientation of the item | | `[data-dragging]` | Present when in the dragging state | **Item Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `index` | `number` | Yes | The index of the item. | | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `snapAlign` | `'start' | 'end' | 'center'` | No | The snap alignment of the item. | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | item | | `[data-index]` | The index of the item | | `[data-inview]` | Present when in viewport | | `[data-orientation]` | The orientation of the item | **NextTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **NextTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | next-trigger | | `[data-orientation]` | The orientation of the nexttrigger | **PrevTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **PrevTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | prev-trigger | | `[data-orientation]` | The orientation of the prevtrigger | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseCarouselReturn` | Yes | | | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | #### Vue **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `slideCount` | `number` | Yes | The total number of slides. Useful for SSR to render the initial ating the snap points. | | `allowMouseDrag` | `boolean` | No | Whether to allow scrolling via dragging with mouse | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `autoplay` | `boolean | { delay: number }` | No | Whether to scroll automatically. The default delay is 4000ms. | | `defaultPage` | `number` | No | The initial page to scroll to when rendered. Use when you don't need to control the page of the carousel. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string item(index: number): string itemGroup: string nextTrigger: string prevTrigger: string indicatorGroup: string indicator(index: number): string }>` | No | The ids of the elements in the carousel. Useful for composition. | | `inViewThreshold` | `number | number[]` | No | The threshold for determining if an item is in view. | | `loop` | `boolean` | No | Whether the carousel should loop around. | | `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the element. | | `padding` | `string` | No | Defines the extra space added around the scrollable area, enabling nearby items to remain partially in view. | | `page` | `number` | No | The controlled page of the carousel. | | `slidesPerMove` | `number | 'auto'` | No | The number of slides to scroll at a time. When set to `auto`, the number of slides to scroll is determined by the `slidesPerPage` property. | | `slidesPerPage` | `number` | No | The number of slides to show at a time. | | `snapType` | `'proximity' | 'mandatory'` | No | The snap type of the item. | | `spacing` | `string` | No | The amount of space between items. | | `translations` | `IntlTranslations` | No | The localized messages to use. | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | root | | `[data-orientation]` | The orientation of the carousel | **AutoplayTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **AutoplayTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | autoplay-trigger | | `[data-orientation]` | The orientation of the autoplaytrigger | | `[data-pressed]` | Present when pressed | **Control Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Control Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | control | | `[data-orientation]` | The orientation of the control | **IndicatorGroup Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **IndicatorGroup Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | indicator-group | | `[data-orientation]` | The orientation of the indicatorgroup | **Indicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `index` | `number` | Yes | The index of the indicator. | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `readOnly` | `boolean` | No | Whether the indicator is read only. | **Indicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | indicator | | `[data-orientation]` | The orientation of the indicator | | `[data-index]` | The index of the item | | `[data-readonly]` | Present when read-only | | `[data-current]` | Present when current | **ItemGroup Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemGroup Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | item-group | | `[data-orientation]` | The orientation of the item | | `[data-dragging]` | Present when in the dragging state | **Item Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `index` | `number` | Yes | The index of the item. | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `snapAlign` | `'start' | 'end' | 'center'` | No | The snap alignment of the item. | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | item | | `[data-index]` | The index of the item | | `[data-inview]` | Present when in viewport | | `[data-orientation]` | The orientation of the item | **NextTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **NextTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | next-trigger | | `[data-orientation]` | The orientation of the nexttrigger | **PrevTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **PrevTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | prev-trigger | | `[data-orientation]` | The orientation of the prevtrigger | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `CarouselApi ` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | #### Svelte **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `slideCount` | `number` | Yes | The total number of slides. Useful for SSR to render the initial ating the snap points. | | `allowMouseDrag` | `boolean` | No | Whether to allow scrolling via dragging with mouse | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `autoplay` | `boolean | { delay: number }` | No | Whether to scroll automatically. The default delay is 4000ms. | | `defaultPage` | `number` | No | The initial page to scroll to when rendered. Use when you don't need to control the page of the carousel. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string item: (index: number) => string itemGroup: string nextTrigger: string prevTrigger: string indicatorGroup: string indicator: (index: number) => string }>` | No | The ids of the elements in the carousel. Useful for composition. | | `inViewThreshold` | `number | number[]` | No | The threshold for determining if an item is in view. | | `loop` | `boolean` | No | Whether the carousel should loop around. | | `onAutoplayStatusChange` | `(details: AutoplayStatusDetails) => void` | No | Function called when the autoplay status changes. | | `onDragStatusChange` | `(details: DragStatusDetails) => void` | No | Function called when the drag status changes. | | `onPageChange` | `(details: PageChangeDetails) => void` | No | Function called when the page changes. | | `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the element. | | `padding` | `string` | No | Defines the extra space added around the scrollable area, enabling nearby items to remain partially in view. | | `page` | `number` | No | The controlled page of the carousel. | | `ref` | `Element` | No | | | `slidesPerMove` | `number | 'auto'` | No | The number of slides to scroll at a time. When set to `auto`, the number of slides to scroll is determined by the `slidesPerPage` property. | | `slidesPerPage` | `number` | No | The number of slides to show at a time. | | `snapType` | `'proximity' | 'mandatory'` | No | The snap type of the item. | | `spacing` | `string` | No | The amount of space between items. | | `translations` | `IntlTranslations` | No | The localized messages to use. | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | root | | `[data-orientation]` | The orientation of the carousel | **AutoplayTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **AutoplayTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | autoplay-trigger | | `[data-orientation]` | The orientation of the autoplaytrigger | | `[data-pressed]` | Present when pressed | **Context Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `render` | `Snippet<[UseCarouselContext]>` | Yes | | **Control 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. | | `ref` | `Element` | No | | **Control Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | control | | `[data-orientation]` | The orientation of the control | **IndicatorGroup 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. | | `ref` | `Element` | No | | **IndicatorGroup Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | indicator-group | | `[data-orientation]` | The orientation of the indicatorgroup | **Indicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `index` | `number` | Yes | The index of the indicator. | | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `readOnly` | `boolean` | No | Whether the indicator is read only. | | `ref` | `Element` | No | | **Indicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | indicator | | `[data-orientation]` | The orientation of the indicator | | `[data-index]` | The index of the item | | `[data-readonly]` | Present when read-only | | `[data-current]` | Present when current | **ItemGroup 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. | | `ref` | `Element` | No | | **ItemGroup Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | item-group | | `[data-orientation]` | The orientation of the item | | `[data-dragging]` | Present when in the dragging state | **Item Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `index` | `number` | Yes | The index of the item. | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | | `snapAlign` | `'start' | 'end' | 'center'` | No | The snap alignment of the item. | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | item | | `[data-index]` | The index of the item | | `[data-inview]` | Present when in viewport | | `[data-orientation]` | The orientation of the item | **NextTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **NextTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | next-trigger | | `[data-orientation]` | The orientation of the nexttrigger | **PrevTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **PrevTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | carousel | | `[data-part]` | prev-trigger | | `[data-orientation]` | The orientation of the prevtrigger | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseCarouselReturn` | Yes | | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | ### Context These are the properties available when using `Carousel.Context`, `useCarouselContext` hook or `useCarousel` hook. **API:** | Property | Type | Description | |----------|------|-------------| | `page` | `number` | The current index of the carousel | | `pageSnapPoints` | `number[]` | The current snap points of the carousel | | `isPlaying` | `boolean` | Whether the carousel is auto playing | | `isDragging` | `boolean` | Whether the carousel is being dragged. This only works when `draggable` is true. | | `canScrollNext` | `boolean` | Whether the carousel is can scroll to the next view | | `canScrollPrev` | `boolean` | Whether the carousel is can scroll to the previous view | | `scrollToIndex` | `(index: number, instant?: boolean) => void` | Function to scroll to a specific item index | | `scrollTo` | `(page: number, instant?: boolean) => void` | Function to scroll to a specific page | | `scrollNext` | `(instant?: boolean) => void` | Function to scroll to the next page | | `scrollPrev` | `(instant?: boolean) => void` | Function to scroll to the previous page | | `getProgress` | `() => number` | Returns the current scroll progress as a percentage | | `getProgressText` | `() => string` | Returns the progress text | | `play` | `VoidFunction` | Function to start/resume autoplay | | `pause` | `VoidFunction` | Function to pause autoplay | | `isInView` | `(index: number) => boolean` | Whether the item is in view | | `refresh` | `VoidFunction` | Function to re-compute the snap points and clamp the page | ## Accessibility Complies with the [Carousel WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/carousel/). # Checkbox ## Anatomy To set up the checkbox correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ### Design impact on the asChild property The `Checkbox.Root` element of the checkbox is a `label` element. This is because the checkbox is a form control and should be associated with a label to provide context and meaning to the user. Otherwise, the HTML and accessibility structure will be invalid. > If you need to use the `asChild` property, make sure that the `label` element is the direct child of the > `Checkbox.Root` component. ## Examples Learn how to use the `Checkbox` component in your project. Let's take a look at the most basic example: **Example: basic** #### React ```tsx import { Checkbox } from '@ark-ui/react/checkbox' import { CheckIcon } from 'lucide-react' export const Basic = () => ( Checkbox Checkbox Checkbox Accept terms and conditions (true) return ( setChecked(e.checked)}> ) } ``` #### Solid ```tsx import { Checkbox } from '@ark-ui/solid/checkbox' import { CheckIcon } from 'lucide-solid' import { createSignal } from 'solid-js' export const Controlled = () => { const [checked, setChecked] = createSignalCheckbox (true) return ( setChecked(e.checked)}> ) } ``` #### Vue ```vueCheckbox Checkbox Controlled checkbox Checkbox Checkbox Checkbox Checkbox Checkbox Accept terms and conditions Accept terms and conditions Accept terms and conditions Checkbox Checkbox Checkbox Checkbox Checkbox Checkbox Checkbox Checkbox {(checkbox) => Checkbox {checkbox.checked.toString()} }{(checkbox) => Checkbox {checkbox().checked.toString()} }Checkbox {{ checkbox.checked.toString() }} {#snippet render(api)} Checkbox {api().checked.toString()} {/snippet}Label Additional Info Error Info Label Additional Info Error Info Label Additional Info Error Info Label Additional Info Error Info Checkbox Checkbox Checkbox Checkbox {items.map((item) => ( ) ``` #### Solid ```tsx import { Checkbox } from '@ark-ui/solid/checkbox' import { CheckIcon } from 'lucide-solid' import { For } from 'solid-js' const items = [ { label: 'React', value: 'react' }, { label: 'Solid', value: 'solid' }, { label: 'Vue', value: 'vue' }, ] export const Group = () => ({item.label} {(item) => ( {item.label} {{ item.label }} {#each items as item} ``` ### Group Controlled Use the `value` and `onValueChange` props to programmatically control the checkbox group's state. This example demonstrates how to manage selected checkboxes in an array and display the current selection. **Example: group-controlled** #### React ```tsx import { Checkbox } from '@ark-ui/react/checkbox' import { CheckIcon } from 'lucide-react' import { useState } from 'react' const items = [ { label: 'React', value: 'react' }, { label: 'Solid', value: 'solid' }, { label: 'Vue', value: 'vue' }, { label: 'Svelte', value: 'svelte' }, ] export const GroupControlled = () => { const [value, setValue] = useState(['react']) return ({item.label} ) } ``` #### Solid ```tsx import { Checkbox } from '@ark-ui/solid/checkbox' import { Check } from 'lucide-solid' import { createSignal, For } from 'solid-js' const items = [ { label: 'React', value: 'react' }, { label: 'Solid', value: 'solid' }, { label: 'Vue', value: 'vue' }, ] export const GroupControlled = () => { const [value, setValue] = createSignal(['react']) const toggleValue = () => { setValue((prev) => (prev[0] === 'react' ? ['solid'] : ['react'])) } return ( <>{items.map((item) => ( {item.label} Selected: {JSON.stringify(value)}{(item) => ( {item.label} {{ item.label }} {#each items as item} {item.label} Selected: {JSON.stringify(value)}``` ### Group Provider Use the `useCheckboxGroup` hook to create the checkbox group store and pass it to the `Checkbox.GroupProvider` component. This provides maximum control over the group programmatically, similar to how `RootProvider` works for individual checkboxes. **Example: group-provider** #### React ```tsx import { Checkbox, useCheckboxGroup } from '@ark-ui/react/checkbox' import { CheckIcon } from 'lucide-react' const items = [ { label: 'React', value: 'react' }, { label: 'Solid', value: 'solid' }, { label: 'Vue', value: 'vue' }, { label: 'Svelte', value: 'svelte' }, ] export const GroupProvider = () => { const group = useCheckboxGroup({ defaultValue: ['react'], name: 'framework', }) return ({items.map((item) => ( ) } ``` #### Solid ```tsx import { Checkbox, useCheckboxGroup } from '@ark-ui/solid/checkbox' import { CheckIcon } from 'lucide-solid' import { For } from 'solid-js' const items = [ { label: 'React', value: 'react' }, { label: 'Solid', value: 'solid' }, { label: 'Vue', value: 'vue' }, { label: 'Svelte', value: 'svelte' }, ] export const GroupProvider = () => { const group = useCheckboxGroup({ defaultValue: ['react'], name: 'framework', }) return ({item.label} {(item) => ( {item.label} {{ item.label }} {#each items as item} ``` ### Group + Form Use the `Checkbox.Group` component within a form to handle multiple checkbox values with form submission. The `name` prop ensures all selected values are collected as an array when the form is submitted using `FormData.getAll()`. **Example: group-with-form** #### React ```tsx import { Checkbox } from '@ark-ui/react/checkbox' import { CheckIcon } from 'lucide-react' const items = [ { label: 'React', value: 'react' }, { label: 'Solid', value: 'solid' }, { label: 'Vue', value: 'vue' }, { label: 'Svelte', value: 'svelte' }, ] export const GroupWithForm = () => ( ) ``` #### Solid ```tsx import { Checkbox } from '@ark-ui/solid/checkbox' import { CheckIcon } from 'lucide-solid' import { For } from 'solid-js' const items = [ { label: 'React', value: 'react' }, { label: 'Solid', value: 'solid' }, { label: 'Svelte', value: 'svelte' }, { label: 'Vue', value: 'vue' }, ] const handleSubmit = (event: Event) => { event.preventDefault() const formData = new FormData(event.target as HTMLFormElement) console.log(formData.getAll('framework')) } export const GroupWithForm = () => ( ) ``` #### Vue ```vue ``` #### Svelte ```svelte ``` ### Group + Invalid Use the `invalid` prop on `Checkbox.Group` to mark the entire group as invalid for validation purposes. This applies the invalid state to all checkboxes within the group. **Example: group-with-invalid** #### React ```tsx import { Checkbox } from '@ark-ui/react/checkbox' import { CheckIcon } from 'lucide-react' const items = [ { label: 'React', value: 'react' }, { label: 'Solid', value: 'solid' }, { label: 'Vue', value: 'vue' }, { label: 'Svelte', value: 'svelte' }, ] export const GroupWithInvalid = () => ({item.label} {items.map((item) => ( ) ``` #### Solid ```tsx import { Checkbox } from '@ark-ui/solid/checkbox' import { CheckIcon } from 'lucide-solid' import { For } from 'solid-js' const items = [ { label: 'React', value: 'react' }, { label: 'Solid', value: 'solid' }, { label: 'Vue', value: 'vue' }, { label: 'Svelte', value: 'svelte' }, ] export const GroupWithInvalid = () => ({item.label} {(item) => ( {item.label} {{ item.label }} {#each items as item (item.value)} ``` ### Group + Select All Implement a "select all" checkbox that controls all checkboxes within a group. The parent checkbox automatically shows an indeterminate state when some (but not all) items are selected, and becomes fully checked when all items are selected. **Example: group-with-select-all** #### React ```tsx import { Checkbox } from '@ark-ui/react/checkbox' import { CheckIcon, MinusIcon } from 'lucide-react' import { useState } from 'react' const items = [ { label: 'React', value: 'react' }, { label: 'Solid', value: 'solid' }, { label: 'Vue', value: 'vue' }, { label: 'Svelte', value: 'svelte' }, ] const CheckboxItem = (props: Checkbox.RootProps) => { return ({item.label} {props.children} ) } ``` #### Solid ```tsx import { Checkbox } from '@ark-ui/solid/checkbox' import { CheckIcon, MinusIcon } from 'lucide-solid' import { For, createSignal, createMemo } from 'solid-js' const items = [ { label: 'React', value: 'react' }, { label: 'Solid', value: 'solid' }, { label: 'Vue', value: 'vue' }, { label: 'Svelte', value: 'svelte' }, ] export const GroupWithSelectAll = () => { const [value, setValue] = createSignalhandleSelectAll(!!e.checked)} > Select All {items.map((item) => ( {item.label} ))}Selected: {JSON.stringify(value)}) } ``` #### Vue ```vuehandleSelectAll(!!details.checked)} > Select All {(item) => ( {item.label} Selected: {JSON.stringify(value())}``` #### Svelte ```svelte {#snippet CheckboxItem(item: (typeof items)[number])}Select All {{ item.label }} Selected: {{ JSON.stringify(value) }}{item.label} ``` ### Group + Fieldset Use the `Fieldset` component with `Checkbox.Group` to provide semantic grouping with legend, helper text, and error text support. **Example: group-with-fieldset** #### React ```tsx import { Checkbox } from '@ark-ui/react/checkbox' import { Fieldset } from '@ark-ui/react/fieldset' import { CheckIcon } from 'lucide-react' const items = [ { label: 'React', value: 'react' }, { label: 'Solid', value: 'solid' }, { label: 'Vue', value: 'vue' }, { label: 'Svelte', value: 'svelte' }, ] export const GroupWithFieldset = () => (handleSelectAll(!!e.checked)} > Select All {#each items as item (item.value)} {@render CheckboxItem(item)} {/each} Selected: {JSON.stringify(value)}Select frameworks {items.map((item) => ( {item.label} Choose your preferred frameworks Error Text Select frameworks {(item) => ( {item().label} Choose your preferred frameworks Error Text Select frameworks {{ item.label }} Choose your preferred frameworks Error Text Select frameworks {#each items as item (item.value)} {item.label} Choose your preferred frameworks Error Text ` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | #### Svelte **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'label'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `checked` | `CheckedState` | No | The controlled checked state of the checkbox | | `defaultChecked` | `CheckedState` | No | The initial checked state of the checkbox when rendered. Use when you don't need to control the checked state of the checkbox. | | `disabled` | `boolean` | No | Whether the checkbox is disabled | | `form` | `string` | No | The id of the form that the checkbox belongs to. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string; hiddenInput: string; control: string; label: string }>` | No | The ids of the elements in the checkbox. Useful for composition. | | `invalid` | `boolean` | No | Whether the checkbox is invalid | | `name` | `string` | No | The name of the input field in a checkbox. Useful for form submission. | | `onCheckedChange` | `(details: CheckedChangeDetails) => void` | No | The callback invoked when the checked state changes. | | `readOnly` | `boolean` | No | Whether the checkbox is read-only | | `ref` | `Element` | No | | | `required` | `boolean` | No | Whether the checkbox is required | | `value` | `string` | No | The value of checkbox input. Useful for form submission. | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-active]` | Present when active or pressed | | `[data-focus]` | Present when focused | | `[data-focus-visible]` | Present when focused with keyboard | | `[data-readonly]` | Present when read-only | | `[data-hover]` | Present when hovered | | `[data-disabled]` | Present when disabled | | `[data-state]` | "indeterminate" | "checked" | "unchecked" | | `[data-invalid]` | Present when invalid | | `[data-required]` | Present when required | **Context Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `render` | `Snippet<[UseCheckboxReturn]>` | No | | **Control 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. | | `ref` | `Element` | No | | **Control Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-active]` | Present when active or pressed | | `[data-focus]` | Present when focused | | `[data-focus-visible]` | Present when focused with keyboard | | `[data-readonly]` | Present when read-only | | `[data-hover]` | Present when hovered | | `[data-disabled]` | Present when disabled | | `[data-state]` | "indeterminate" | "checked" | "unchecked" | | `[data-invalid]` | Present when invalid | | `[data-required]` | Present when required | **Group 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. | | `defaultValue` | `string[]` | No | The initial value of `value` when uncontrolled | | `disabled` | `boolean` | No | If `true`, the checkbox group is disabled | | `invalid` | `boolean` | No | If `true`, the checkbox group is invalid | | `name` | `string` | No | The name of the input fields in the checkbox group (Useful for form submission). | | `onValueChange` | `(value: string[]) => void` | No | The callback to call when the value changes | | `readOnly` | `boolean` | No | If `true`, the checkbox group is read-only | | `ref` | `Element` | No | | | `value` | `string[]` | No | The controlled value of the checkbox group | **GroupProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `() => { isChecked: (val: string | undefined) => boolean; value: string[]; name: string | undefined; disabled: boolean; readOnly: boolean; invalid: boolean; setValue: (newValue: string[]) => void; addValue: (val: string) => void; toggleValue: (val: string) => void; getItemProps: (itemProps: CheckboxGroupItemProps) =>...` | Yes | | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **HiddenInput Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'input'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Indicator 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. | | `indeterminate` | `boolean` | No | | | `ref` | `Element` | No | | **Indicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-active]` | Present when active or pressed | | `[data-focus]` | Present when focused | | `[data-focus-visible]` | Present when focused with keyboard | | `[data-readonly]` | Present when read-only | | `[data-hover]` | Present when hovered | | `[data-disabled]` | Present when disabled | | `[data-state]` | "indeterminate" | "checked" | "unchecked" | | `[data-invalid]` | Present when invalid | | `[data-required]` | Present when required | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-active]` | Present when active or pressed | | `[data-focus]` | Present when focused | | `[data-focus-visible]` | Present when focused with keyboard | | `[data-readonly]` | Present when read-only | | `[data-hover]` | Present when hovered | | `[data-disabled]` | Present when disabled | | `[data-state]` | "indeterminate" | "checked" | "unchecked" | | `[data-invalid]` | Present when invalid | | `[data-required]` | Present when required | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseCheckboxReturn` | Yes | | | `asChild` | `Snippet<[PropsFn<'label'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | ### Context These are the properties available when using `Checkbox.Context`, `useCheckboxContext` hook or `useCheckbox` hook. **API:** | Property | Type | Description | |----------|------|-------------| | `checked` | `boolean` | Whether the checkbox is checked | | `disabled` | `boolean` | Whether the checkbox is disabled | | `indeterminate` | `boolean` | Whether the checkbox is indeterminate | | `focused` | `boolean` | Whether the checkbox is focused | | `checkedState` | `CheckedState` | The checked state of the checkbox | | `setChecked` | `(checked: CheckedState) => void` | Function to set the checked state of the checkbox | | `toggleChecked` | `VoidFunction` | Function to toggle the checked state of the checkbox | ## Accessibility Complies with the [Checkbox WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/). ### Keyboard Support **`Space`** Description: Toggle the checkbox # Clipboard ## Anatomy To set up the Clipboard correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples Learn how to use the `Clipboard` component in your project. Let's take a look at the most basic example: **Example: basic** #### React ```tsx import { Clipboard } from '@ark-ui/react/clipboard' import { CheckIcon, ClipboardCopyIcon } from 'lucide-react' export const Basic = () => { return ( Copy this link }> Copy this link }> Copy this link Copy this link {#snippet copied()} {/snippet} Copy this link {(clipboard) => ( {clipboard.copied ?)}: } {clipboard.copied ? 'Copied!' : 'Copy'} Value: {clipboard.value} Copy this link {(clipboard) => ( )}}> Copied! Value: {clipboard().value}Copy this link {{ clipboard.copied ? 'Copied!' : 'Copy' }} Value: {{ clipboard.value }} Copy this link {#snippet render(clipboard)} {#if clipboard().copied}{/snippet}{:else} {/if} {#if clipboard().copied} Copied! {:else} Copy {/if} Value: {clipboard().value} { if (details.copied) { setCopyCount((prev) => prev + 1) } }} > ) } ``` #### Solid ```tsx import { Clipboard } from '@ark-ui/solid/clipboard' import { CheckIcon, ClipboardCopyIcon } from 'lucide-solid' import { Show, createSignal } from 'solid-js' export const CopyStatus = () => { const [copyCount, setCopyCount] = createSignal(0) return (}> Copy Copied {copyCount} times
{ if (details.copied) { setCopyCount((prev) => prev + 1) } }} > ) } ``` #### Vue ```vue}> Copied {copyCount()} times
Copied {{ copyCount }} times
{ if (details.copied) { copyCount += 1 } }} > ``` ### Controlled Control the clipboard value externally by managing the state yourself and using `onValueChange` to handle updates. **Example: controlled** #### React ```tsx import { Clipboard } from '@ark-ui/react/clipboard' import { CheckIcon, ClipboardCopyIcon } from 'lucide-react' import { useState } from 'react' export const Controlled = () => { const [url, setUrl] = useState('https://ark-ui.com') const handleUrlChange = () => { setUrl('https://chakra-ui.com') } return ({#snippet copied()} {/snippet} Copied {copyCount} times
setUrl(value)}> ) } ``` #### Solid ```tsx import { Clipboard } from '@ark-ui/solid/clipboard' import { CheckIcon, ClipboardCopyIcon } from 'lucide-solid' import { Show, createSignal } from 'solid-js' export const Controlled = () => { const [url, setUrl] = createSignal('https://ark-ui.com') const handleUrlChange = () => { setUrl('https://chakra-ui.com') } return (Copy this link }> setUrl(value)}> ) } ``` #### Vue ```vueCopy this link }> Copy this link Copy this link {#snippet copied()} {/snippet} Copy this link }> Copy this link }> Copy this link Copy this link {#snippet copied()} {/snippet} Copy this link (5 second timeout) }> Copy this link (5 second timeout) }> Copy this link (5 second timeout) Copy this link (5 second timeout) {#snippet copied()} {/snippet} {(clipboard) => } {(clipboard) => ( )} {#snippet render(clipboard)} {/snippet} }> Copy }> {#snippet copied()} {/snippet} | ReactPortal | Promise<...>` | No | | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | clipboard | | `[data-part]` | input | | `[data-copied]` | Present when copied state is true | | `[data-readonly]` | Present when read-only | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | clipboard | | `[data-part]` | label | | `[data-copied]` | Present when copied state is true | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseClipboardReturn` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | clipboard | | `[data-part]` | trigger | | `[data-copied]` | Present when copied state is true | **ValueText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | #### Solid **Root 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. | | `defaultValue` | `string` | No | The initial value to be copied to the clipboard when rendered. Use when you don't need to control the value of the clipboard. | | `ids` | `Partial<{ root: string; input: string; label: string }>` | No | The ids of the elements in the clipboard. Useful for composition. | | `onStatusChange` | `(details: CopyStatusDetails) => void` | No | The function to be called when the value is copied to the clipboard | | `onValueChange` | `(details: ValueChangeDetails) => void` | No | The function to be called when the value changes | | `timeout` | `number` | No | The timeout for the copy operation | | `value` | `string` | No | The controlled value of the clipboard | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | clipboard | | `[data-part]` | root | | `[data-copied]` | Present when copied state is true | **Control 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. | **Control Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | clipboard | | `[data-part]` | control | | `[data-copied]` | Present when copied state is true | **Indicator 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. | | `copied` | `number | boolean | Node | ArrayElement | (string & {})` | No | | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'input'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | clipboard | | `[data-part]` | input | | `[data-copied]` | Present when copied state is true | | `[data-readonly]` | Present when read-only | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'label'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | clipboard | | `[data-part]` | label | | `[data-copied]` | Present when copied state is true | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseClipboardReturn` | Yes | | | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | clipboard | | `[data-part]` | trigger | | `[data-copied]` | Present when copied state is true | **ValueText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'span'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | #### Vue **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `defaultValue` | `string` | No | The initial value to be copied to the clipboard when rendered. Use when you don't need to control the value of the clipboard. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string; input: string; label: string }>` | No | The ids of the elements in the clipboard. Useful for composition. | | `modelValue` | `string` | No | The v-model value of the clipboard | | `timeout` | `number` | No | The timeout for the copy operation | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | clipboard | | `[data-part]` | root | | `[data-copied]` | Present when copied state is true | **Control Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Control Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | clipboard | | `[data-part]` | control | | `[data-copied]` | Present when copied state is true | **Indicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Input Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | clipboard | | `[data-part]` | input | | `[data-copied]` | Present when copied state is true | | `[data-readonly]` | Present when read-only | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | clipboard | | `[data-part]` | label | | `[data-copied]` | Present when copied state is true | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `ClipboardApi ` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | clipboard | | `[data-part]` | trigger | | `[data-copied]` | Present when copied state is true | **ValueText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | #### Svelte **Root 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. | | `defaultValue` | `string` | No | The initial value to be copied to the clipboard when rendered. Use when you don't need to control the value of the clipboard. | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string; input: string; label: string }>` | No | The ids of the elements in the clipboard. Useful for composition. | | `onStatusChange` | `(details: CopyStatusDetails) => void` | No | The function to be called when the value is copied to the clipboard | | `onValueChange` | `(details: ValueChangeDetails) => void` | No | The function to be called when the value changes | | `ref` | `Element` | No | | | `timeout` | `number` | No | The timeout for the copy operation | | `value` | `string` | No | The controlled value of the clipboard | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | clipboard | | `[data-part]` | root | | `[data-copied]` | Present when copied state is true | **Context Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `render` | `Snippet<[UseClipboardContext]>` | No | | **Control 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. | | `ref` | `Element` | No | | **Control Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | clipboard | | `[data-part]` | control | | `[data-copied]` | Present when copied state is true | **Indicator 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. | | `copied` | `Snippet<[]>` | No | | | `ref` | `Element` | No | | **Input Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'input'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Input Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | clipboard | | `[data-part]` | input | | `[data-copied]` | Present when copied state is true | | `[data-readonly]` | Present when read-only | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'label'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | clipboard | | `[data-part]` | label | | `[data-copied]` | Present when copied state is true | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseClipboardReturn` | Yes | | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | clipboard | | `[data-part]` | trigger | | `[data-copied]` | Present when copied state is true | **ValueText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | ### Context These are the properties available when using `Clipboard.Context`, `useClipboardContext` hook or `useClipboard` hook. **API:** | Property | Type | Description | |----------|------|-------------| | `copied` | `boolean` | Whether the value has been copied to the clipboard | | `value` | `string` | The value to be copied to the clipboard | | `setValue` | `(value: string) => void` | Set the value to be copied to the clipboard | | `copy` | `VoidFunction` | Copy the value to the clipboard | # Collapsible ## Animation You can use CSS animations to create smooth transitions for opening and closing the Collapsible content. Utilize the `data-state` attribute in combination with the `--height` CSS variable to animate the open and closed states. ```css @keyframes slideDown { from { height: 0; } to { height: var(--height); } } @keyframes slideUp { from { height: var(--height); } to { height: 0; } } [data-scope='collapsible'][data-part='content'][data-state='open'] { animation: slideDown 250ms; } [data-scope='collapsible'][data-part='content'][data-state='closed'] { animation: slideUp 200ms; } ``` ## Examples Learn how to use the `Collapsible` component in your project. Let's examine the most basic example **Example: basic** #### React ```tsx import { Collapsible } from '@ark-ui/react/collapsible' import { ChevronRightIcon } from 'lucide-react' export const Basic = () => ( Toggle Content Toggle Content Toggle Content Toggle Content Toggle Content Toggle Content Toggle Content Toggle Content Show More Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.
Show More Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.
Show More Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.
Show More Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.
Getting Started Welcome to the documentation. Here are some topics to explore:
Installation To install the package, run one of the following commands:
npm install @ark-ui/react
Configuration Configure your project settings to use Ark UI components.
Getting Started Welcome to the documentation. Here are some topics to explore:
Installation To install the package, run one of the following commands:
npm install @ark-ui/solid
Configuration Configure your project settings to use Ark UI components.
Getting Started Welcome to the documentation. Here are some topics to explore:
Installation To install the package, run one of the following commands:
npm install @ark-ui/vue
Configuration Configure your project settings to use Ark UI components.
Getting Started Welcome to the documentation. Here are some topics to explore:
Installation To install the package, run one of the following commands:
npm install @ark-ui/svelte
Configuration Configure your project settings to use Ark UI components.
alert('on exit')}> ) ``` #### Solid ```tsx import { Collapsible } from '@ark-ui/solid/collapsible' import { ChevronRightIcon } from 'lucide-solid' export const OnExitComplete = () => (Toggle Content alert('on exit')}> ) ``` #### Vue ```vueToggle Content Toggle Content ``` ### Lazy Mount To delay the mounting of the `Collapsible.Content`, use the `lazyMount` prop **Example: lazy-mount** #### React ```tsx import { Collapsible } from '@ark-ui/react/collapsible' import { ChevronRightIcon } from 'lucide-react' export const LazyMount = () => ((logs = [...logs, `Exit complete at ${new Date().toLocaleTimeString()}`])}> {#if logs.length > 0}Toggle (with exit callback) This content has an exit callback {/if}Exit logs:
-
{#each logs as log}
Toggle Content Toggle Content Toggle Content Toggle (lazy mount) This content is only mounted when opened Toggle Content Toggle Content Toggle Content Toggle (unmount on exit) This content is unmounted when closed Toggle Content Toggle Content Toggle Content Toggle (lazy + unmount) This content is lazy mounted and unmounted on exit Toggle Content Toggle Content Toggle Content ``` > If you're using the `Collapsible.RootProvider` component, you don't need to use the `Collapsible.Root` component. ### Programmatic Control Use the `useCollapsible` hook with `Collapsible.RootProvider` to programmatically control the collapsible using the `setOpen()` method and read state properties like `open` and `visible`. **Example: programmatic-open** #### React ```tsx import { Collapsible, useCollapsible } from '@ark-ui/react/collapsible' import { ChevronRightIcon } from 'lucide-react' export const ProgrammaticOpen = () => { const collapsible = useCollapsible() return ( <>Toggle (with external control) This collapsible is controlled externally Open: {String(collapsible.open)}
Visible: {String(collapsible.visible)}
Toggle Content Open: {String(collapsible().open)}
Visible: {String(collapsible().visible)}
Toggle Content Open: {{ String(collapsible.open) }}
Visible: {{ String(collapsible.visible) }}
Toggle Content Open: {String(collapsible().open)}
Visible: {String(collapsible().visible)}
Toggle Content Color Toggle ColorFormat ✓ ✓ ✓ Pick color Color Toggle ColorFormat ✓ ✓ ✓ Pick color Color Toggle ColorFormat ✓ ✓ ✓ Pick color Color Toggle ColorFormat ✓ ✓ ✓ Pick color setColor(e.value)}> ) } ``` #### Solid ```tsx import { ColorPicker, parseColor } from '@ark-ui/solid/color-picker' import { createSignal } from 'solid-js' export const Controlled = () => { const [color, setColor] = createSignal(parseColor('hsl(0, 100%, 50%)')) return (Color ✓ ✓ ✓ Pick color setColor(e.value)} onValueChangeEnd={(e) => console.log(e.valueAsString)} > ) } ``` #### Vue ```vueColor ✓ ✓ ✓ Pick color Color ✓ ✓ ✓ Pick color ``` > Alternatively, the `onValueChangeEnd` prop can be used to listen for when the user has finished selecting a color. ### Field The `Field` component helps manage form-related state and accessibility attributes of a color picker. It includes handling ARIA labels, helper text, and error text to ensure proper accessibility. **Example: with-field** #### React ```tsx import { ColorPicker, parseColor } from '@ark-ui/react/color-picker' import { Field } from '@ark-ui/react/field' export const WithField = (props: Field.RootProps) => (Selected color: {value.toString('hex')}
Color Toggle ColorFormat ✓ ✓ ✓ Pick color Label Additional Info Error Info Label Additional Info Error Info Label Additional Info Error Info Label Additional Info Error Info Color Toggle ColorFormat ✓ ✓ ✓ Pick color Color Toggle ColorFormat ✓ ✓ ✓ Pick color Color Toggle ColorFormat ✓ ✓ ✓ Pick color ``` > If you're using the `ColorPicker.RootProvider` component, you don't need to use the `ColorPicker.Root` component. ## API Reference ### Props **Component API Reference** #### React **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `closeOnSelect` | `boolean` | No | Whether to close the color picker when a swatch is selected | | `defaultFormat` | `ColorFormat` | No | The initial color format when rendered. Use when you don't need to control the color format of the color picker. | | `defaultOpen` | `boolean` | No | The initial open state of the color picker when rendered. Use when you don't need to control the open state of the color picker. | | `defaultValue` | `Color` | No | The initial color value when rendered. Use when you don't need to control the color value of the color picker. | | `disabled` | `boolean` | No | Whether the color picker is disabled | | `format` | `ColorFormat` | No | The controlled color format to use | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string; control: string; trigger: string; label: string; input: string; hiddenInput: string; content: string; area: string; areaGradient: string; positioner: string; formatSelect: string; areaThumb: string; channelInput: (id: string) => string; channelSliderTrack: (id: ColorChannel) => string; channe...` | No | The ids of the elements in the color picker. Useful for composition. | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `initialFocusEl` | `() => HTMLElement | null` | No | The initial focus element when the color picker is opened. | | `inline` | `boolean` | No | Whether to render the color picker inline | | `invalid` | `boolean` | No | Whether the color picker is invalid | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `name` | `string` | No | The name for the form input | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component | | `onFormatChange` | `(details: FormatChangeDetails) => void` | No | Function called when the color format changes | | `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component | | `onOpenChange` | `(details: OpenChangeDetails) => void` | No | Handler that is called when the user opens or closes the color picker. | | `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component | | `onValueChange` | `(details: ValueChangeDetails) => void` | No | Handler that is called when the value changes, as the user drags. | | `onValueChangeEnd` | `(details: ValueChangeDetails) => void` | No | Handler that is called when the user stops dragging. | | `open` | `boolean` | No | The controlled open state of the color picker | | `openAutoFocus` | `boolean` | No | Whether to auto focus the color picker when it is opened | | `positioning` | `PositioningOptions` | No | The positioning options for the color picker | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `readOnly` | `boolean` | No | Whether the color picker is read-only | | `required` | `boolean` | No | Whether the color picker is required | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | | `value` | `Color` | No | The controlled color value of the color picker | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | root | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | | `[data-invalid]` | Present when invalid | **AreaBackground Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **AreaBackground Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | area-background | | `[data-invalid]` | Present when invalid | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | **Area Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `xChannel` | `ColorChannel` | No | | | `yChannel` | `ColorChannel` | No | | **Area Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | area | | `[data-invalid]` | Present when invalid | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | **AreaThumb Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **AreaThumb Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | area-thumb | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **ChannelInput Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `channel` | `ExtendedColorChannel` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `orientation` | `Orientation` | No | | **ChannelInput Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | channel-input | | `[data-channel]` | The color channel of the channelinput | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **ChannelSliderLabel Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ChannelSliderLabel Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | channel-slider-label | | `[data-channel]` | The color channel of the channelsliderlabel | **ChannelSlider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `channel` | `ColorChannel` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `orientation` | `Orientation` | No | | **ChannelSlider Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | channel-slider | | `[data-channel]` | The color channel of the channelslider | | `[data-orientation]` | The orientation of the channelslider | **ChannelSliderThumb Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ChannelSliderThumb Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | channel-slider-thumb | | `[data-channel]` | The color channel of the channelsliderthumb | | `[data-disabled]` | Present when disabled | | `[data-orientation]` | The orientation of the channelsliderthumb | **ChannelSliderTrack Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ChannelSliderTrack Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | channel-slider-track | | `[data-channel]` | The color channel of the channelslidertrack | | `[data-orientation]` | The orientation of the channelslidertrack | **ChannelSliderValueText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ChannelSliderValueText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | channel-slider-value-text | | `[data-channel]` | The color channel of the channelslidervaluetext | **Content Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Content Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | content | | `[data-placement]` | The placement of the content | | `[data-nested]` | popover | | `[data-has-nested]` | popover | | `[data-state]` | "open" | "closed" | **Control Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Control Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | control | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | | `[data-invalid]` | Present when invalid | | `[data-state]` | "open" | "closed" | | `[data-focus]` | Present when focused | **EyeDropperTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **EyeDropperTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | eye-dropper-trigger | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **FormatSelect Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **FormatTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **HiddenInput Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | label | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | | `[data-invalid]` | Present when invalid | | `[data-required]` | Present when required | | `[data-focus]` | Present when focused | **Positioner Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseColorPickerReturn` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **SwatchGroup Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **SwatchIndicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Swatch Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `string | Color` | Yes | The color value | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `respectAlpha` | `boolean` | No | Whether to include the alpha channel in the color | **Swatch Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | swatch | | `[data-state]` | "checked" | "unchecked" | | `[data-value]` | The value of the item | **SwatchTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `string | Color` | Yes | The color value | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `disabled` | `boolean` | No | Whether the swatch trigger is disabled | **SwatchTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | swatch-trigger | | `[data-state]` | "checked" | "unchecked" | | `[data-value]` | The value of the item | | `[data-disabled]` | Present when disabled | **TransparencyGrid Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `size` | `string` | No | | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | trigger | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | | `[data-invalid]` | Present when invalid | | `[data-placement]` | The placement of the trigger | | `[data-state]` | "open" | "closed" | | `[data-focus]` | Present when focused | **ValueSwatch Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `respectAlpha` | `boolean` | No | Whether to include the alpha channel in the color | **ValueText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `format` | `ColorStringFormat` | No | | **ValueText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | value-text | | `[data-disabled]` | Present when disabled | | `[data-focus]` | Present when focused | **View Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `format` | `ColorFormat` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | #### Solid **Root 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. | | `closeOnSelect` | `boolean` | No | Whether to close the color picker when a swatch is selected | | `defaultFormat` | `ColorFormat` | No | The initial color format when rendered. Use when you don't need to control the color format of the color picker. | | `defaultOpen` | `boolean` | No | The initial open state of the color picker when rendered. Use when you don't need to control the open state of the color picker. | | `defaultValue` | `Color` | No | The initial color value when rendered. Use when you don't need to control the color value of the color picker. | | `disabled` | `boolean` | No | Whether the color picker is disabled | | `format` | `ColorFormat` | No | The controlled color format to use | | `ids` | `Partial<{ root: string; control: string; trigger: string; label: string; input: string; hiddenInput: string; content: string; area: string; areaGradient: string; positioner: string; formatSelect: string; areaThumb: string; channelInput: (id: string) => string; channelSliderTrack: (id: ColorChannel) => string; channe...` | No | The ids of the elements in the color picker. Useful for composition. | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `initialFocusEl` | `() => HTMLElement | null` | No | The initial focus element when the color picker is opened. | | `inline` | `boolean` | No | Whether to render the color picker inline | | `invalid` | `boolean` | No | Whether the color picker is invalid | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `name` | `string` | No | The name for the form input | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component | | `onFormatChange` | `(details: FormatChangeDetails) => void` | No | Function called when the color format changes | | `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component | | `onOpenChange` | `(details: OpenChangeDetails) => void` | No | Handler that is called when the user opens or closes the color picker. | | `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component | | `onValueChange` | `(details: ValueChangeDetails) => void` | No | Handler that is called when the value changes, as the user drags. | | `onValueChangeEnd` | `(details: ValueChangeDetails) => void` | No | Handler that is called when the user stops dragging. | | `open` | `boolean` | No | The controlled open state of the color picker | | `openAutoFocus` | `boolean` | No | Whether to auto focus the color picker when it is opened | | `positioning` | `PositioningOptions` | No | The positioning options for the color picker | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `readOnly` | `boolean` | No | Whether the color picker is read-only | | `required` | `boolean` | No | Whether the color picker is required | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | | `value` | `Color` | No | The controlled color value of the color picker | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | root | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | | `[data-invalid]` | Present when invalid | **AreaBackground 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. | **AreaBackground Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | area-background | | `[data-invalid]` | Present when invalid | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | **Area 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. | | `xChannel` | `ColorChannel` | No | | | `yChannel` | `ColorChannel` | No | | **Area Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | area | | `[data-invalid]` | Present when invalid | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | **AreaThumb 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. | **AreaThumb Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | area-thumb | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **ChannelInput Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `channel` | `ExtendedColorChannel` | Yes | | | `asChild` | `(props: ParentProps<'input'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `orientation` | `Orientation` | No | | **ChannelInput Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | channel-input | | `[data-channel]` | The color channel of the channelinput | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **ChannelSliderLabel Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'label'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ChannelSliderLabel Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | channel-slider-label | | `[data-channel]` | The color channel of the channelsliderlabel | **ChannelSlider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `channel` | `ColorChannel` | Yes | | | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `orientation` | `Orientation` | No | | **ChannelSlider Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | channel-slider | | `[data-channel]` | The color channel of the channelslider | | `[data-orientation]` | The orientation of the channelslider | **ChannelSliderThumb 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. | **ChannelSliderThumb Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | channel-slider-thumb | | `[data-channel]` | The color channel of the channelsliderthumb | | `[data-disabled]` | Present when disabled | | `[data-orientation]` | The orientation of the channelsliderthumb | **ChannelSliderTrack 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. | **ChannelSliderTrack Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | channel-slider-track | | `[data-channel]` | The color channel of the channelslidertrack | | `[data-orientation]` | The orientation of the channelslidertrack | **ChannelSliderValueText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'span'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ChannelSliderValueText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | channel-slider-value-text | | `[data-channel]` | The color channel of the channelslidervaluetext | **Content 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. | **Content Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | content | | `[data-placement]` | The placement of the content | | `[data-nested]` | popover | | `[data-has-nested]` | popover | | `[data-state]` | "open" | "closed" | **Control 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. | **Control Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | control | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | | `[data-invalid]` | Present when invalid | | `[data-state]` | "open" | "closed" | | `[data-focus]` | Present when focused | **EyeDropperTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **EyeDropperTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | eye-dropper-trigger | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **FormatSelect Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'select'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **FormatTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **HiddenInput Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'input'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'label'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | label | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | | `[data-invalid]` | Present when invalid | | `[data-required]` | Present when required | | `[data-focus]` | Present when focused | **Positioner 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. | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseColorPickerReturn` | Yes | | | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **SwatchGroup 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. | **SwatchIndicator 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. | **Swatch Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `string | Color` | Yes | The color value | | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `respectAlpha` | `boolean` | No | Whether to include the alpha channel in the color | **Swatch Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | swatch | | `[data-state]` | "checked" | "unchecked" | | `[data-value]` | The value of the item | **SwatchTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `string | Color` | Yes | The color value | | `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `disabled` | `boolean` | No | Whether the swatch trigger is disabled | **SwatchTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | swatch-trigger | | `[data-state]` | "checked" | "unchecked" | | `[data-value]` | The value of the item | | `[data-disabled]` | Present when disabled | **TransparencyGrid 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. | | `size` | `string` | No | | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | trigger | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | | `[data-invalid]` | Present when invalid | | `[data-placement]` | The placement of the trigger | | `[data-state]` | "open" | "closed" | | `[data-focus]` | Present when focused | **ValueSwatch 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. | | `respectAlpha` | `boolean` | No | Whether to include the alpha channel in the color | **ValueText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'span'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `format` | `ColorStringFormat` | No | | **ValueText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | value-text | | `[data-disabled]` | Present when disabled | | `[data-focus]` | Present when focused | **View Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `format` | `ColorFormat` | Yes | | | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | #### Vue **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `closeOnSelect` | `boolean` | No | Whether to close the color picker when a swatch is selected | | `defaultFormat` | `ColorFormat` | No | The initial color format when rendered. Use when you don't need to control the color format of the color picker. | | `defaultOpen` | `boolean` | No | The initial open state of the color picker when rendered. Use when you don't need to control the open state of the color picker. | | `defaultValue` | `Color` | No | The initial color value when rendered. Use when you don't need to control the color value of the color picker. | | `disabled` | `boolean` | No | Whether the color picker is disabled | | `format` | `ColorFormat` | No | The controlled color format to use | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string; control: string; trigger: string; label: string; input: string; hiddenInput: string; content: string; area: string; areaGradient: string; positioner: string; formatSelect: string; areaThumb: string; channelInput(id: string): string; channelSliderTrack(id: ColorChannel): string; channelSliderT...` | No | The ids of the elements in the color picker. Useful for composition. | | `initialFocusEl` | `() => HTMLElement | null` | No | The initial focus element when the color picker is opened. | | `inline` | `boolean` | No | Whether the color picker is inline | | `invalid` | `boolean` | No | Whether the color picker is invalid | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `modelValue` | `Color` | No | The v-model value of the color picker | | `name` | `string` | No | The name for the form input | | `open` | `boolean` | No | The controlled open state of the color picker | | `openAutoFocus` | `boolean` | No | Whether to auto focus the color picker when it is opened | | `positioning` | `PositioningOptions` | No | The positioning options for the color picker | | `readOnly` | `boolean` | No | Whether the color picker is read-only | | `required` | `boolean` | No | Whether the color picker is required | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | root | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | | `[data-invalid]` | Present when invalid | **AreaBackground Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **AreaBackground Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | area-background | | `[data-invalid]` | Present when invalid | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | **Area Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `xChannel` | `ColorChannel` | No | | | `yChannel` | `ColorChannel` | No | | **Area Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | area | | `[data-invalid]` | Present when invalid | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | **AreaThumb Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **AreaThumb Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | area-thumb | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **ChannelInput Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `channel` | `ExtendedColorChannel` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `orientation` | `Orientation` | No | | **ChannelInput Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | channel-input | | `[data-channel]` | The color channel of the channelinput | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **ChannelSliderLabel Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ChannelSliderLabel Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | channel-slider-label | | `[data-channel]` | The color channel of the channelsliderlabel | **ChannelSlider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `channel` | `ColorChannel` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `orientation` | `Orientation` | No | | **ChannelSlider Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | channel-slider | | `[data-channel]` | The color channel of the channelslider | | `[data-orientation]` | The orientation of the channelslider | **ChannelSliderThumb Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ChannelSliderThumb Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | channel-slider-thumb | | `[data-channel]` | The color channel of the channelsliderthumb | | `[data-disabled]` | Present when disabled | | `[data-orientation]` | The orientation of the channelsliderthumb | **ChannelSliderTrack Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ChannelSliderTrack Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | channel-slider-track | | `[data-channel]` | The color channel of the channelslidertrack | | `[data-orientation]` | The orientation of the channelslidertrack | **ChannelSliderValueText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ChannelSliderValueText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | channel-slider-value-text | | `[data-channel]` | The color channel of the channelslidervaluetext | **Content Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Content Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | content | | `[data-placement]` | The placement of the content | | `[data-nested]` | popover | | `[data-has-nested]` | popover | | `[data-state]` | "open" | "closed" | **Control Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Control Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | control | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | | `[data-invalid]` | Present when invalid | | `[data-state]` | "open" | "closed" | | `[data-focus]` | Present when focused | **EyeDropperTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **EyeDropperTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | eye-dropper-trigger | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **FormatSelect Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **FormatTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **HiddenInput Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | label | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | | `[data-invalid]` | Present when invalid | | `[data-required]` | Present when required | | `[data-focus]` | Present when focused | **Positioner Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `ColorPickerApiExternal state: {colorPicker().valueAsString}
Color Toggle ColorFormat ✓ ✓ ✓ Pick color ` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **SwatchGroup Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **SwatchIndicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Swatch Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `string | Color` | Yes | The color value | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `respectAlpha` | `boolean` | No | Whether to include the alpha channel in the color | **Swatch Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | swatch | | `[data-state]` | "checked" | "unchecked" | | `[data-value]` | The value of the item | **SwatchTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `string | Color` | Yes | The color value | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `disabled` | `boolean` | No | Whether the swatch trigger is disabled | **SwatchTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | swatch-trigger | | `[data-state]` | "checked" | "unchecked" | | `[data-value]` | The value of the item | | `[data-disabled]` | Present when disabled | **TransparencyGrid Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `size` | `string` | No | | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | trigger | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | | `[data-invalid]` | Present when invalid | | `[data-placement]` | The placement of the trigger | | `[data-state]` | "open" | "closed" | | `[data-focus]` | Present when focused | **ValueSwatch Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `respectAlpha` | `boolean` | No | Whether to include the alpha channel in the color | **ValueText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `format` | `ColorStringFormat` | No | | **ValueText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | value-text | | `[data-disabled]` | Present when disabled | | `[data-focus]` | Present when focused | **View Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `format` | `ColorFormat` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | #### Svelte **Root 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. | | `closeOnSelect` | `boolean` | No | Whether to close the color picker when a swatch is selected | | `defaultFormat` | `ColorFormat` | No | The initial color format when rendered. Use when you don't need to control the color format of the color picker. | | `defaultOpen` | `boolean` | No | The initial open state of the color picker when rendered. Use when you don't need to control the open state of the color picker. | | `defaultValue` | `Color` | No | The initial color value when rendered. Use when you don't need to control the color value of the color picker. | | `disabled` | `boolean` | No | Whether the color picker is disabled | | `format` | `ColorFormat` | No | The controlled color format to use | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string; control: string; trigger: string; label: string; input: string; hiddenInput: string; content: string; area: string; areaGradient: string; positioner: string; formatSelect: string; areaThumb: string; channelInput: (id: string) => string; channelSliderTrack: (id: ColorChannel) => string; channe...` | No | The ids of the elements in the color picker. Useful for composition. | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `initialFocusEl` | `() => HTMLElement | null` | No | The initial focus element when the color picker is opened. | | `inline` | `boolean` | No | Whether to render the color picker inline | | `invalid` | `boolean` | No | Whether the color picker is invalid | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `name` | `string` | No | The name for the form input | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component | | `onFormatChange` | `(details: FormatChangeDetails) => void` | No | Function called when the color format changes | | `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component | | `onOpenChange` | `(details: OpenChangeDetails) => void` | No | Handler that is called when the user opens or closes the color picker. | | `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component | | `onValueChange` | `(details: ValueChangeDetails) => void` | No | Handler that is called when the value changes, as the user drags. | | `onValueChangeEnd` | `(details: ValueChangeDetails) => void` | No | Handler that is called when the user stops dragging. | | `open` | `boolean` | No | The controlled open state of the color picker | | `openAutoFocus` | `boolean` | No | Whether to auto focus the color picker when it is opened | | `positioning` | `PositioningOptions` | No | The positioning options for the color picker | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `readOnly` | `boolean` | No | Whether the color picker is read-only | | `ref` | `Element` | No | | | `required` | `boolean` | No | Whether the color picker is required | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | | `value` | `Color` | No | The controlled color value of the color picker | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | root | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | | `[data-invalid]` | Present when invalid | **AreaBackground 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. | | `ref` | `Element` | No | | **AreaBackground Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | area-background | | `[data-invalid]` | Present when invalid | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | **Area 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. | | `ref` | `Element` | No | | | `xChannel` | `ColorChannel` | No | | | `yChannel` | `ColorChannel` | No | | **Area Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | area | | `[data-invalid]` | Present when invalid | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | **AreaThumb 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. | | `ref` | `Element` | No | | **AreaThumb Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | area-thumb | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **ChannelInput Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `channel` | `ExtendedColorChannel` | Yes | | | `asChild` | `Snippet<[PropsFn<'input'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `orientation` | `Orientation` | No | | | `ref` | `Element` | No | | **ChannelInput Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | channel-input | | `[data-channel]` | The color channel of the channelinput | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **ChannelSliderLabel Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'label'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **ChannelSliderLabel Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | channel-slider-label | | `[data-channel]` | The color channel of the channelsliderlabel | **ChannelSlider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `channel` | `ColorChannel` | Yes | | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `orientation` | `Orientation` | No | | | `ref` | `Element` | No | | **ChannelSlider Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | channel-slider | | `[data-channel]` | The color channel of the channelslider | | `[data-orientation]` | The orientation of the channelslider | **ChannelSliderThumb 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. | | `ref` | `Element` | No | | **ChannelSliderThumb Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | channel-slider-thumb | | `[data-channel]` | The color channel of the channelsliderthumb | | `[data-disabled]` | Present when disabled | | `[data-orientation]` | The orientation of the channelsliderthumb | **ChannelSliderTrack 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. | | `ref` | `Element` | No | | **ChannelSliderTrack Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | channel-slider-track | | `[data-channel]` | The color channel of the channelslidertrack | | `[data-orientation]` | The orientation of the channelslidertrack | **ChannelSliderValueText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **ChannelSliderValueText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | channel-slider-value-text | | `[data-channel]` | The color channel of the channelslidervaluetext | **Content 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. | | `ref` | `Element` | No | | **Content Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | content | | `[data-placement]` | The placement of the content | | `[data-nested]` | popover | | `[data-has-nested]` | popover | | `[data-state]` | "open" | "closed" | **Context Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `render` | `Snippet<[UseColorPickerContext]>` | Yes | | **Control 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. | | `ref` | `Element` | No | | **Control Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | control | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | | `[data-invalid]` | Present when invalid | | `[data-state]` | "open" | "closed" | | `[data-focus]` | Present when focused | **EyeDropperTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **EyeDropperTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | eye-dropper-trigger | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | | `[data-readonly]` | Present when read-only | **FormatSelect Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'select'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **FormatTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **HiddenInput Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'input'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'label'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | label | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | | `[data-invalid]` | Present when invalid | | `[data-required]` | Present when required | | `[data-focus]` | Present when focused | **Positioner 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. | | `ref` | `Element` | No | | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseColorPickerReturn` | Yes | | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state | | `present` | `boolean` | No | Whether the node is present (controlled by the user) | | `ref` | `Element` | No | | | `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **SwatchGroup 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. | | `ref` | `Element` | No | | **SwatchIndicator 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. | | `ref` | `Element` | No | | **Swatch Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `string | Color` | Yes | The color value | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | | `respectAlpha` | `boolean` | No | Whether to include the alpha channel in the color | **Swatch Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | swatch | | `[data-state]` | "checked" | "unchecked" | | `[data-value]` | The value of the item | **SwatchTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `string | Color` | Yes | The color value | | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `disabled` | `boolean` | No | Whether the swatch trigger is disabled | | `ref` | `Element` | No | | **SwatchTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | swatch-trigger | | `[data-state]` | "checked" | "unchecked" | | `[data-value]` | The value of the item | | `[data-disabled]` | Present when disabled | **TransparencyGrid 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. | | `ref` | `Element` | No | | | `size` | `string` | No | | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | trigger | | `[data-disabled]` | Present when disabled | | `[data-readonly]` | Present when read-only | | `[data-invalid]` | Present when invalid | | `[data-placement]` | The placement of the trigger | | `[data-state]` | "open" | "closed" | | `[data-focus]` | Present when focused | **ValueSwatch 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. | | `ref` | `Element` | No | | | `respectAlpha` | `boolean` | No | Whether to include the alpha channel in the color | **ValueText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `format` | `ColorStringFormat` | No | | | `ref` | `Element` | No | | **ValueText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | color-picker | | `[data-part]` | value-text | | `[data-disabled]` | Present when disabled | | `[data-focus]` | Present when focused | **View Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `format` | `ColorFormat` | Yes | | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | ### Context These are the properties available when using `ColorPicker.Context`, `useColorPickerContext` hook or `useColorPicker` hook. **API:** | Property | Type | Description | |----------|------|-------------| | `dragging` | `boolean` | Whether the color picker is being dragged | | `open` | `boolean` | Whether the color picker is open | | `inline` | `boolean` | Whether the color picker is rendered inline | | `value` | `Color` | The current color value (as a string) | | `valueAsString` | `string` | The current color value (as a Color object) | | `setValue` | `(value: string | Color) => void` | Function to set the color value | | `getChannelValue` | `(channel: ColorChannel) => string` | Function to set the color value | | `getChannelValueText` | `(channel: ColorChannel, locale: string) => string` | Function to get the formatted and localized value of a specific channel | | `setChannelValue` | `(channel: ColorChannel, value: number) => void` | Function to set the color value of a specific channel | | `format` | `ColorFormat` | The current color format | | `setFormat` | `(format: ColorFormat) => void` | Function to set the color format | | `alpha` | `number` | The alpha value of the color | | `setAlpha` | `(value: number) => void` | Function to set the color alpha | | `setOpen` | `(open: boolean) => void` | Function to open or close the color picker | ## Accessibility ### Keyboard Support **`Enter`** Description: When focus is on the trigger, opens the color picker
When focus is on a trigger of a swatch, selects the color (and closes the color picker)
When focus is on the input or channel inputs, selects the color **`ArrowLeft`** Description: When focus is on the color area, decreases the hue value of the color
When focus is on the channel sliders, decreases the value of the channel **`ArrowRight`** Description: When focus is on the color area, increases the hue value of the color
When focus is on the channel sliders, increases the value of the channel **`ArrowUp`** Description: When focus is on the color area, increases the saturation value of the color
When focus is on the channel sliders, increases the value of the channel **`ArrowDown`** Description: When focus is on the color area, decreases the saturation value of the color
When focus is on the channel sliders, decreases the value of the channel **`Esc`** Description: Closes the color picker and moves focus to the trigger # Combobox ## Anatomy To set up the combobox correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples Learn how to use the `Combobox` component in your project. Let's take a look at the most basic example **Example: basic** #### React ```tsx import { Combobox, useListCollection } from '@ark-ui/react/combobox' import { useFilter } from '@ark-ui/react/locale' import { Portal } from '@ark-ui/react/portal' export const Basic = () => { const { contains } = useFilter({ sensitivity: 'base' }) const { collection, filter } = useListCollection({ initialItems: ['React', 'Solid', 'Vue', 'Svelte'], filter: contains, }) const handleInputChange = (details: Combobox.InputValueChangeDetails) => { filter(details.inputValue) } return (Framework Open Clear Frameworks {collection.items.map((item) => ({item} ✓ Framework Open Clear Frameworks {(item) => ( {item} ✓ Framework Open Clear Frameworks {{ item }} ✓ Framework Open Clear Frameworks {#each collection().items as item (item)}{item} ✓ Framework Open Clear {collection.group().map(([type, group]) => ( {type} {group.map((item) => ({item.label} ✓ Framework Open Clear {([type, group]) => ( {type} {(item) => ( {item.label} ✓ Framework Open Clear {{ type }} {{ item.label }} ✓ ``` ### Field The `Field` component helps manage form-related state and accessibility attributes of a combobox. It includes handling ARIA labels, helper text, and error text to ensure proper accessibility. **Example: with-field** #### React ```tsx import { Combobox, useListCollection } from '@ark-ui/react/combobox' import { Field } from '@ark-ui/react/field' import { useFilter } from '@ark-ui/react/locale' export const WithField = (props: Field.RootProps) => { const { contains } = useFilter({ sensitivity: 'base' }) const { collection, filter } = useListCollection({ initialItems, filter: contains, }) const handleInputChange = (details: Combobox.InputValueChangeDetails) => { filter(details.inputValue) } return (Framework Open Clear {#each collection().group() as [type, group]} {type} {#each group as item}{item.label} ✓ Label Open Clear {collection.items.map((item) => ( {item} ✓ Additional Info Error Info Label Open Clear {(item) => ( {item} ✓ Additional Info Error Info Label Open Clear Frameworks {{ item }} ✓ Additional Info Error Info Framework Open Clear {#each collection().items as item (item)} {item} ✓ Additional Info Error Info Framework Open Clear Frameworks {collection.items.map((item) => ({item} ✓ Framework Open Clear Frameworks {(item) => ( {item} ✓ Framework Open Clear Frameworks {{ item }} ✓ Framework Open Clear {#each collection.items as item} {item} ✓ Framework {collection.items.map((item) => ( {item.label} ✓ Framework {(item) => ( }> )}{item.label} ✓ Framework {{ item.label }} ✓ ``` ### Rehydrate Value In some cases, where a combobox has a `defaultValue` or `value` but the `collection` is not loaded yet, here's how to rehydrate the value and populate the input value. **Example: rehydrate-value** #### React ```tsx import { Combobox, useCombobox, useComboboxContext, useListCollection } from '@ark-ui/react/combobox' import { Portal } from '@ark-ui/react/portal' import { useRef, useState } from 'react' import { useAsync } from 'react-use' // The meat of the example is here. // It rehydrates the input value when the combobox is mounted. function ComboboxRehydrateValue() { const combobox = useComboboxContext() const hydrated = useRef(false) if (combobox.value.length && combobox.collection.size && !hydrated.current) { combobox.syncSelectedItems() hydrated.current = true } return null } export const RehydrateValue = () => { const [inputValue, setInputValue] = useState('') const { collection, set } = useListCollectionFramework {#each collection().items as item (item.value)} {#snippet asChild(props)} {/each}{item.label} ✓ {/snippet}({ initialItems: [], itemToString: (item) => item.name, itemToValue: (item) => item.name, }) const combobox = useCombobox({ collection, defaultValue: ['C-3PO'], placeholder: 'Example: Dexter', inputValue, onInputValueChange: (e) => setInputValue(e.inputValue), }) const state = useAsync(async () => { const response = await fetch(`https://swapi.py4e.com/api/people/?search=${inputValue}`) const data = await response.json() set(data.results) }, [inputValue, set]) return ( Search Star Wars Characters {state.loading ? ( Loading... ) : state.error ? ( {state.error.message} ) : ( collection.items.map((item) => ( {item.name} - {item.height}cm / {item.mass}kg )) )}({ initialItems: [], itemToString: (item) => item.name, itemToValue: (item) => item.name, }) const combobox = useCombobox(() => ({ collection: collection(), defaultValue: ['C-3PO'], placeholder: 'Example: Dexter', inputValue: inputValue(), onInputValueChange: (e) => setInputValue(e.inputValue), })) const state = useAsync(async (signal) => { const response = await fetch(`https://swapi.py4e.com/api/people/?search=${inputValue()}`, { signal }) const data = await response.json() set(data.results) }) createEffect(on(inputValue, () => state.load())) return ( Search Star Wars Characters {state.loading() ? ( Loading... ) : state.error() ? ( {state.error()?.message} ) : ( {(item) => ( )}{item.name} - {item.height}cm / {item.mass}kg )}Search Star Wars Characters Loading... {{ state.error.value.message }} {{ item.name }} - {{ item.height }}cm / {{ item.mass }}kg Search Star Wars Characters {#if _state.loading()} Loading... {:else if _state.error()} {_state.error()?.message} {:else} {#each collection().items as item (item.name)} {item.name} - {item.height}cm / {item.mass}kg {/each} {/if}Framework Open Clear Frameworks {collection.items.map((item) => ({(context) => } Framework Open Clear Frameworks {(item) => ( {(context) => } Framework Open Clear Frameworks {{ item }} Framework Open Clear Frameworks {#each collection().items as item (item)}{#snippet render(context)} {/snippet} ({ initialItems: [], }) const handleInputChange = (details: Combobox.InputValueChangeDetails) => { if (details.reason === 'input-change') { const items = suggestList.map((item) => `${details.inputValue}@${item}`) set(items) } } return ( Framework Open {collection.items.map((item) => ( {item} ✓ ({ initialItems: [], }) const handleInputChange = (details: Combobox.InputValueChangeDetails) => { if (details.reason === 'input-change') { const items = suggestList.map((item) => `${details.inputValue}@${item}`) set(items) } } return ( Framework Open {(item) => ( {item} ✓ Framework Open {{ item }} ✓ Framework Open {#each collection().items as item (item)} {item} ✓
- `.
- **Textarea**: Fixed `ResizeObserver` warning.
- **Timer**: Fixed stopping issue when switching tabs; resolved issue where `action` prop was passed to `ActionTrigger`.
- **Toast**: Fixed keyboard navigation skipping close button.
- **Toggle Group**: Fixed `data-focus` not being removed on blur.
# Changelog
## [Unreleased]
## [5.30.0] - 2025-12-10
### Added
- **Date Picker**: Added `required` and `invalid` props
- **Number Input**: Added `onValueCommit` callback that fires when the input loses focus or Enter is pressed
- **Pagination**:
- Added `FirstTrigger` and `LastTrigger` components for navigating to first/last page
- Added `boundaryCount` parameter for controlling boundary pages (start/end)
- Implemented balanced pagination algorithm for consistent UI with max 7 elements
- **Radio Group**: Added `invalid` and `required` props with corresponding `data-*` and `aria-*` attributes
- **Tree View**: Added `scrollToIndexFn` prop to enable keyboard navigation in virtualized trees
### Fixed
- **Accordion, Menu**: Fixed issue where querying elements by `aria-controls` attribute could fail when lazy mounting the content
- **Color Picker**: Added `role="dialog"` to content and `aria-haspopup="dialog"` to trigger when not inline for better accessibility
- **Date Picker**: Fixed issue where date picker input does not update format when locale changes
- **Floating Panel**:
- Fixed `dir` prop now properly delegated to all panel parts
- Fixed double-click behavior improvements and to check `event.defaultPrevented` for custom behavior
- **Listbox**:
- Fixed issue where `data-highlighted` wasn't applied to the first item when using `autoHighlight` with input filtering
- **Number Input**:
- Fixed improved controlled usage sync
- Fixed issue where input element doesn't sync when `formatOptions` changes dynamically
- Ensured cursor position is preserved when `Enter` key is pressed and formatting is triggered
- Fixed cursor jumping to start when value is changed externally via props while user is typing
- **Pagination**: Fixed ellipsis showing when only 1 page gap
- **Rating Group**: Fixed issue where rating group becomes unfocusable via keyboard when value is 0
- **Tooltip**: Fixed tooltip not showing when scrolling with pointer over trigger
### Changed
- **Tree View**: `getVisibleNodes()` now returns `{ node, indexPath }[]` instead of `node[]`
## [5.29.1] - 2025-11-22
### Fixed
- **Fieldset**: Fixed `aria-describedby` resolution to correctly reference helper text and error text IDs, and corrected
`aria-labelledby` to use legend ID instead of label ID
- **Floating Panel**:
- Fixed resize trigger issue with `n` axis by explicitly setting `top: 0`
- Fixed `draggable` and `resizable` options not being respected when set to `false`
- **Presence**: Fixed regression where UNMOUNT transition might not be called consistently
## [5.29.0] - 2025-11-20
### Added
- **Carousel, Color Picker, Combobox, Date Picker, Select**: Added `value` to `OpenChangeDetails` for better context
when handling open state changes
- **Carousel**: Added support for `autoSize` prop to allow variable width/height slide items
- **Splitter**:
- Added `Splitter.ResizeTriggerIndicator` to render an indicator when resizing
- Exported `getLayout` and `getSplitterLayout` functions for calculating splitter panel layouts
- **Toast**: Exposed viewport offset as CSS variables on the toast group element
### Fixed
- **Carousel**:
- Fixed dragging behavior that stops working after switching browser tabs or scrolling the page
- Fixed dragging not working after scrolling with mouse wheel when `allowMouseDrag` is enabled
- **Combobox**: Fixed `onHighlightChange` not being invoked when collection is filtered to empty
- **Date Picker**: Fixed issue where the range date picker crashes when typing the end date first and blurring the input
field multiple times
- **File Upload**: Fixed issue where clicking on non-interactive children inside the dropzone doesn't open the file
picker
- **Presence**: Fixed a bug where elements get stuck in unmountSuspended state during rapid state updates
- **Radio Group**:
- Fixed inconsistent application of `data-focus-visible` and `data-focus` attributes
- **Splitter**: Fixed disabled splitter showing resize cursor and allowing dragging
- **Tabs**:
- Fixed tabs indicator position not updating when inactive tabs change size
- **Tags Input**: Fixed issue where item delete trigger doesn't have `data-*` attached
## [5.28.0] - 2025-11-14
### Added
- **General**: Exported `InteractOutsideEvent`, `FocusOutsideEvent`, and `PointerDownOutsideEvent` types for better type
safety
- **Carousel**:
- Added `Carousel.AutoplayIndicator` component for conditionally rendering content based on autoplay state
- Added `Carousel.ProgressText` component for displaying current page progress (e.g., "1 / 5")
- **Toast**: Exported `ToastOptions` and `ToastStoreProps` types for better type safety
### Changed
- **useListCollection**: Updated `initialItems` to accept `readonly` arrays for better compatibility with immutable data
patterns.
### Fixed
- **Combobox**:
- Fixed focus stealing in controlled open mode
- Removed problematic `aria-hidden` behavior to allow interaction with other page elements
- **Marquee**: Fixed `Marquee.Content` not receiving `data-v-*` attribute for scoped styles when using `v-for` at the
root level.
## [5.27.1] - 2025-11-02
### Fixed
- **Dialog, Popover**: Improved shadow DOM support for interact outside and focus trap detection
- **Marquee**: Fixed Firefox flicker and added GPU acceleration
- **Dialog**: Fixed layout shift issue when using `scrollbar-gutter: stable` in CSS
- **Slider**: Fixed `onValueChangeEnd` callback not triggering for programmatic value changes
## [5.27.0] - 2025-11-01
### Added
- **Marquee** [New]: Initial release of marquee component for continuously scrolling content
### Fixed
- **Angle Slider**: Resolved an issue where dragging the thumb from non-center positions caused unexpected value jumps.
The thumb now maintains consistent positioning relative to the initial click point.
- **Slider**: Fixed a problem where the thumb offset shifted dynamically during dragging, resulting in value jumps. The
offset now remains constant from the pointer throughout the drag operation.
- **Dialog**: Fix issue where `Dialog.Backdrop` does not respect exit animations when closing. The backdrop now properly
uses the presence composable to enable CSS transitions and animations on close.
- **Bottom Sheet**: Fix issue where `BottomSheet.Backdrop` does not respect exit animations when closing.
- **Tour**: Fix issue where `Tour.Backdrop` does not respect exit animations when closing.
- **Tabs**: Fix issue where `Tab.Content` does not respect exit animations when switching tabs.
- **Date Picker**: Resolved a crash in the range date picker occurring when users typed the end date first by
implementing `null`/`undefined` checks for date property access.
- **Radio Group**: Reverted to `offsetLeft`/`offsetTop` calculations to restore correct indicator positioning within
scrollable container contexts.
- **Tour**:
- Corrected improper effect cleanup procedures
- Fixed wait step functionality
- Added step validation on mount to verify configuration validity
## [5.26.2] - 2025-10-18
### Fixed
- **Angle Slider**: Fix accessibility violation where the slider thumb element lacked an accessible name. The thumb now
supports `aria-label` and `aria-labelledby` props, and automatically falls back to the label element's ID for proper
ARIA labeling.
- **Select**: Fix accessibility violation where the required state was not set correctly to on the trigger.
- **Tags Input**: Fix issue where entering a custom tag with combobox integration required pressing `Enter` twice. The
tags-input now correctly handles custom values when the combobox has no highlighted item (`aria-activedescendant` is
empty), allowing the tag to be added on the first `Enter` press.
## [5.26.1] - 2025-10-15
### Fixed
- **Checkbox**
- Fix issue where setting initial checked state to `indeterminate` doesn't work
- Ensure `api.checkedState` returns the correct checked state (`boolean | "indeterminate"`)
- **Collapsible**: Fix issue where `dir` prop value was hardcoded to `ltr` instead of using the provided value
- **Combobox**: Fix issue where controlled single-select combobox does not propagate its initial value to `inputValue`
- **Listbox**: Fix issue where pressing Enter key when no highlighted item still calls `event.preventDefault()`
- **Radio Group**: Refactor to use `getBoundingClientRect()` for precise indicator positioning
- **Slider**
- Fix issue where slider could stop abruptly when scrubbing thumb
- Fix issue where range slider thumbs become stuck when dragged to the same position without `minStepsBetweenThumbs`
- **Tabs**: Refactor to use `getBoundingClientRect()` for precise indicator positioning
- **Tags Input**: Fix issue where `maxLength` doesn't apply to the edit input as well
## [5.26.0] - 2025-10-08
### Added
- **Collapsible**: Add support for `collapsedHeight` and `collapsedWidth` props to control the dimensions of the
collapsible content when in its collapsed state.
- **Focus Trap**: Allow elements referenced by `aria-controls` to be included in the trap scope. This makes it possible
for menus, popovers, etc. to be portalled and work correctly.
- **Pagination**: Add `getPageUrl` prop for generating `href` attributes when using pagination as links.
```ts
const service = useMachine(pagination.machine, {
type: 'link',
getPageUrl: ({ page, pageSize }) => `/products?page=${page}&size=${pageSize}`,
})
```
- **Select**: Add `SelectRootComponentProps` type export for better component type composition.
- **Listbox**: Add `ListboxRootComponentProps` type export for better component type composition.
- **Combobox**: Add `ComboboxRootComponentProps` type export for better component type composition.
- **TreeView**:
- Add `TreeViewRootComponentProps` type export for better component type composition.
- (Experimental) Add support for node renaming functionality:
- Add `TreeViewNodeRenameInput` component for inline node label editing
- Add `canRename` prop to control which nodes can be renamed
- Add `renameStart`, `beforeRename`, and `renameComplete` event emitters for rename lifecycle
- Add `CheckedChangeDetails`, `LoadChildrenErrorDetails`, `RenameStartDetails`, and `RenameCompleteDetails` type
exports
### Fixed
- **Scroll Area**: Fix RTL horizontal scrollbar positioning on Safari
- **Slider**: Fix issue where slider continues dragging when disabled during drag operation.
- **Switch**: Fix issue where `data-active` is inconsistently applied when `disabled` state changes at runtime
## [5.25.1] - 2025-09-27
### Fixed
- **Date Picker**
- Fix issue where year range picker doesn't show the hovered range
- Fix issue where quarter presets returns incorrect date
- **FormatByte**: Add support for `unitSystem` property to allow changing between decimal (1000 bytes) and binary (1024
bytes) systems.
- **Number Input**: When `formatOptions` is used (like `style: "currency"`), the cursor would jump to the end of the
input when typing in the middle. The cursor now maintains its relative position during formatting changes.
- **Pin Input**: Fix issue where using the keyboard shortcuts `Cmd+Backspace` and `Cmd+Delete` to delete text in pin
inputs would insert "undefined" instead of clearing the field.
- **Scroll Area**: Fix issue where resize tracking was not observing the root element, which caused the scrollbar to not
update when the root element's size changed.
## [5.25.0] - 2025-09-16
### Added
- Added `mergeProps` utility for combining multiple props objects with proper event handler and className merging.
- Added `createContext` utility for creating typed React contexts with improved DX.
```tsx
import { createContext } from '@ark-ui/solid/utils'
```
## [5.24.1] - 2025-09-14
### Fixed
- **General**: Fix issue where `mergeProps` throws when `props` is `undefined` or `null`
## [5.24.0] - 2025-09-14
### Removed
- **TimePicker**: The TimePicker component has been removed from this release. This component was never part of the
public API and was considered experimental. It had significant bugs and usability issues across all frameworks and
locales, making it unsuitable for production use.
**Migration**: We recommend building a custom time picker using the Select component for simple use cases, or
implementing a time grid pattern for more complex scenarios.
### Added
- **Combobox**: Add `alwaysSubmitOnEnter` prop to allow bypassing the default two-step behavior (Enter to close
combobox, then Enter to submit form) and instead submit the form immediately on Enter press. This is useful for
single-field autocomplete forms where Enter should submit the form directly.
- **Dismissable**: Add support for layer types in dismissable layer stack. Layers can now be categorized as `dialog`,
`popover`, `menu`, or `listbox`. This enables:
- `data-nested` attribute on nested layers of the same type
- `data-has-nested` attribute on parent layers with nested children of the same type
- `--nested-layer-count` CSS variable indicating the number of nested layers of the same type
### Changed
- **Hover Card**: Change default delay values for hover card to improve accessibility.
- `openDelay`: from `700ms` to `600ms`
- **Tooltip**: Change default delay values for tooltip to improve accessibility.
[Learn more](https://www.nngroup.com/articles/timing-exposing-content)
- `openDelay`: from `1000ms` to `400ms`
- `closeDelay`: from `500ms` to `150ms`
### Fixed
- **Editable**: Allow text selection in editable preview when `autoResize` is enabled
Previously, when `autoResize` was set to `true`, the preview element had `userSelect: "none"` applied, preventing
users from selecting text. This has been fixed by removing the `userSelect` style property.
- **File Upload**: Fix regression where clicking the trigger doesn't open the file picker when used within the dropzone
- **Menu**:
- Fix issue where keyboard activation of menu items with `target="_blank"` would open two tabs
- Fix issue where hovering a partially visible item with pointer causes it to scroll into view
- **Tabs**: Fix issue where `ids` for `item` and `content` could not be customized
- **Toast**: Allow creating a toast store without any arguments
## [5.23.0] - 2025-09-08
### Added
- **Field**: Add `data-required` attribute to `Field.Label`
- **Select, Combobox, Listbox, TreeView**: Export `RootComponent` and `RootProviderComponent` types which are useful
when building compositions that wrap the `Root` and `RootProvider` components and you still want type-safety for the
collection.
### Fixed
- **Menu**: Fix `Menu.ItemText` not working inside `Menu.TriggerItem`
## [5.22.0] - 2025-08-28
### Added
- **Combobox**: Add `ComboboxEmpty` component to display content when the combobox has no items
- **Listbox**: Add `ListboxEmpty` component to display content when the listbox has no items
- **Hover Card**: Add support for `disabled` prop
### Fixed
- **Collection**: Fix issue where disabled items could be reached via typeahead
- **Color Picker**: Fix issue where color picker was not working correctly in RTL mode
- **Date Picker**: Fix issue where datepicker doesn't revert to a valid value when the input value exceeds the min/max
and blurred
- **Dismissable**: Expose `onRequestDismiss` custom event handler for event a parent layer requests the child layer to
dismiss. If prevented via `event.preventDefault()`, the child layer will not dismiss when the parent layer is
dismissed.
- **Number Input**
- Omit the input `pattern` when `formatOptions` is provided. This prevents native pattern validation from conflicting
with formatted values (e.g., currency or percent).
- Handle empty values consistently across all format options.
- Add `data-scrubbing` attribute to the number input parts.
- **Tags Input**: Fix issue where highlighted item doesn't clear when tabbing out of the input to an external button
within the `control` part.
- **Tooltip**
- Set `closeOnPointerdown` to `false` when `closeOnClick` is set to `false`
- Reduce bundle size by replacing `@zag-js/store` dependency with a lightweight store implementation.
## [5.21.0] - 2025-08-24
### Added
- **Composables**: Add `useAsyncList` and `useCollator` composables for managing asynchronous list operations and
locale-aware string comparison
- **Toast**: Export type definitions `ToastActionOptions`, `ToastPlacement`, `ToastPromiseOptions`, `ToastStatus`,
`ToastStatusChangeDetails`, and `ToastType`
### Changed
- **Fieldset**
- Update Legend component to render as `div` instead of `legend` element for improved styling flexibility
- Add `aria-labelledby` attribute to fieldset root for better accessibility by linking to legend
### Fixed
- **Date Picker**
- Clear hovered range state after completing range selection instead of waiting for pointer to leave the calendar
area.
- Fix issue where month and year select labels don't update correctly when using `min`/`max` constraints.
- Expose `disabled` on `api.getMonths()` and `api.getYears()` results to indicate options out of range for current
constraints.
- **Listbox**
- Fix issue where first enabled item should be highlighted by default when listbox receives focus and no item is
currently highlighted.
- Add `getElement` to `scrollToIndexFn` details
- Track collection changes and clear `highlightedValue` if the item is no longer in the collection.
- **ScrollArea**
- Avoid detecting hover state from portalled descendants.
- Add `data-dragging` attribute to scroll area parts.
- **Select**: Add `getElement` to `scrollToIndexFn` details
- **Combobox**: Add `getElement` to `scrollToIndexFn` details
## [5.20.0] - 2025-08-20
### Added
- **Highlight Word**: Add `exactMatch` option that enables whole-word matching using regex word boundaries.
### Fixed
- **Menu**: Fix context menu repositioning logic
- **Scroll Area**: Add `data-hover` to scroll area
## [5.19.0] - 2025-08-18
### Added
- **ScrollArea [NEW]**: Add support for new scroll area component.
### Fixed
- **ListCollection**
- Avoid recomputing groups on every call to `at()` and `indexOf()`
- Fixed bug in `find()` method (was checking `!= null` instead of `!== -1`)
- **GridCollection**: Avoid recomputing rows on every call to `getRows()`
- **Menu**
- Add `data-state` attribute for context menu trigger
- Fix context menu positioning bug where reopening at the same coordinates fails to reposition
## [5.18.4] - 2025-08-14
### Fixed
- **Listbox**: Add support for navigating grid collections
- **Carousel**:
- Fix an issue where the carousel would not update when `slideCount` or `autoplay` props change.
- Fix an issue where `loop: false` was ignored when using autoplay. Now, the carousel will stop when it gets to the
last slide.
- **Date Picker**: Expose `data-inline` attribute on Content part to enable distinct styling for inline date pickers
versus popover date pickers.
- **Menu**: Fix issue where `onCheckedChange` could be called twice on checkbox or radio item
- **Radio Group**: Fixed issue where arrow key navigation doesn't apply `data-focus-visible` on the newly focused item.
- **TagsInput**: Export `InputValueChangeDetails` type
- **Field**: Fix issue where `asChild` prop is not being applied to the input and select components, leading to
hydration mismatch.
### Changed
- **Async List**: Improve type inference for descriptors
- **Framework Components**: Improve runtime performance of components
## [5.18.3] - 2025-08-01
### Fixed
- **Carousel**: Fix issue where controlled carousel ignores last slide
## [5.18.2] - 2025-07-26
### Fixed
- **Dialog**
- Sync content `--layer-index` with positioner and backdrop
- Decouple `trapFocus` from `modal` so it's possible to set `modal=false` and `trapFocus=true`
## [5.18.1] - 2025-07-23
### Fixed
- **Menu**: Fixed hydration issue when rendering `Menu.Separator`
- **Date Picker**: Fixed issue where hovered range was connect to selected values, when it shouldn't
- **Tree View**: Fixed issue where tree view doesn't scroll into view when content overflows.
## [5.18.0] - 2025-07-22
### Added
- **Collection**: Add `useListSelection` composable for managing collection item selection with support for
single/multiple selection modes
```vue
```
- **File Upload**: Add support for `v-model:acceptedFiles` and `defaultAcceptedFiles` to programmatically control the
accepted files
- **Signature Pad**: Add support for `v-model:paths` and `defaultPaths` to programmatically control the paths
- **Date Picker**: Added hover range preview support for date picker range selection. Added `inHoveredRange`,
`firstInHoveredRange`, and `lastInHoveredRange` properties to `DayTableCellState` with corresponding data attributes
`data-in-hover-range`, `data-hover-range-start`, and `data-hover-range-end`.
Hover range states are only active when not overlapping with actual selected range, enabling distinct styling for
hover preview vs actual selection in range mode.
### Fixed
- **Date Picker**: Fix date comparison issues when time components are involved. This resolves critical issues with date
comparison operations when different date types (`CalendarDate`, `CalendarDateTime`, `ZonedDateTime`) are mixed,
particularly in scenarios involving time components.
## [5.17.0] - 2025-07-18
### Added
- **Checkbox**: Add `CheckboxGroupProvider` component for external checkbox group state management
### Fixed
- **Carousel**: Fix issue where full page carousel could trap scrolling
- **ListCollection**: Export `UseListCollectionReturn` type
- **TreeCollection**: Fix issue where the `filter` method completely deletes the children key from the node when there
are no matching children
- **Number Input**: Fix issue where default pattern does not allow negative numbers with decimal point
- **File Upload**
- Export `FileError`, `FileMimeType`, and `FileRejection` types
- Fix issue where calling `api.setFiles` invokes validation with incorrect `acceptedFiles`
- Fix issue where the browser might not be able to infer the mime type of a file due to limitations, drag source or
security restrictions. As a fallback in the file validation logic, we now infer the mime type from the file
extension.
## [5.16.1] - 2025-07-05
### Fixed
- **Combobox**
- Expose `reason` to `onOpenChange` and `onInputValueChange` callbacks
- Expose `api.clearHighlightedValue` function to clear highlighted value
- **Date Picker**
- Fix issue where datepicker errors when setting `selectionMode=range` and `minView=year`
- Fix issue where `focusedValue` could not be fully controlled
- **Toast**: Fix issue where toast `title` or `description` could not accept VNodes.
- **Listbox**: Select highlighted item only if it exists in the collection
- **Progress**: Improve `valueAsString` formatting
- **Select**
- Select highlighted item only if it exists in the collection
- Expose `api.clearHighlightedValue` function to clear highlighted value
- **Tour**: Fix an issue where the `goto` function in `StepActionMap` doesn't work when passing step IDs (string)
- **Tree View**: Expose `id` in the tree node state
## [5.16.0] - 2025-07-01
### Added
- **Color Picker**: Add support for `inline` prop to render color picker inline
- **Date Picker**: Add support for `inline` prop to render the date calendar inline
### Fixed
- **Color Picker**: Auto-prefix Hex values with `#` if missing when using the `hex` channel input
- **Menu**: Fix interaction outside detection for focusable context trigger
- **Tree View**: Improve support for rendering tree items as links
## [5.15.3] - 2025-06-27
### Fixed
- **Combobox, Select, Listbox**: Fix issue where rehydrating `defaultValue` or `value` after fetching items doesn't
update the `valueAsString`
## [5.15.2] - 2025-06-26
### Fixed
- **General**: Fix issue where some Zag packages were not included in the package.json `dependencies` and
`devDependencies`. This causes import errors when using the `@ark-ui/vue` package.
- **Date Picker**: Fix issue with keyboard selection where setting unavailable date causes month view to behave
differently from clicking with mouse
- **Toast**: Fix issue where app crashes when `toaster.promise` is called without loading option. The `loading` option
is now required. A warning will be logged if it is not provided
- **Tree View**
- Fix issue where clicking a branch with indeterminate state doesn't check its child nodes
- Remove `aria-busy` attribute from branch trigger when not loading children
- Expose node details in `onExpandChange`, `onSelectionChange` and `onFocusChange`
- **Angle Slider**: Fix issue where scrubbing doesn't feel smooth on touch devices
- **Timer**:
- Fix issue where timer could continue beyond `targetMs` when window is not visible
- Add validation to ensure `startMs` and `targetMs` are configured correctly
- Fix `progressPercent` calculation for countdown timers
## [5.15.1] - 2025-06-23
### Fixed
- **Listbox**: Fix issue where `Listbox.ItemContext` was not exported
## [5.15.0] - 2025-06-23
### Added
- **Tree View**
- Add support for checkbox state for checkbox trees via `defaultCheckedValue`, `checkedValue`, `onCheckedChange` props
- Add callback for when `loadChildren` fails via `onLoadChildrenError` prop
### Fixed
- **Progress**
- Fix issue where setting orientation to `vertical` don't work
- Fix issue where setting `defaultValue` to `null` doesn't show indeterminate state
## [5.14.2] - 2025-06-19
### Fixed
- **General**: Ensure pointerdown or click event handlers only execute when the main button is clicked
- **Tree View**: Exported `TreeViewNodeState` and `TreeViewNodeProps` types from `@zag-js/tree-view`
### Changed
- **Collection**: Improve the APIs around `tree.flatten(...)` and `flattenedToTree` to ensure the original node
properties are preserved.
> Previously, `tree.flatten()` would return an array of objects with `value` and `label` stripping out the original
> node properties.
```ts
const tree = new TreeCollection({
rootNode: {
value: 'ROOT',
children: [{ value: 'child1' }, { value: 'child2' }],
},
})
const flattened = tree.flatten()
const reconstructed = flattenedToTree(flattened)
console.log(reconstructed.rootNode)
// {
// value: "ROOT",
// children: [{ value: "child1" }, { value: "child2" }],
// }
```
## [5.14.1] - 2025-06-17
### Fixed
- **Popover**: Fixed issue where `onOpenChange` could be called twice when controlled
- **File Utils**: Improved `downloadFile` function to handle webview scenarios
- **Toast**: Fixed issue where toast's CSS variables don't apply correctly
- **Combobox**:
- Fixed issue where `onInputValueChange` could be called twice when selecting an item
- Fixed issue where combobox with `allowCustomValue: true` used within in a form requires two enter keypress to submit
## [5.14.0] - 2025-06-10
### Added
- **Editable**: Added support for `activationMode=none`
- **Collection**
- Exposed `copy` method
- Added support for `getParentNodes` to accept a value or index path
### Fixed
- **Collection**: Fixed issue where entrypoint `@ark-ui/vue/collection` was not working as expected
- **Carousel**: Fixed issue where carousel crashes when `slidesPerPage` is 0
- **File Upload**: Prevented `undefined` in `acceptedFiles` when no files accepted
- **Select**: Fixed issue where highlighted item could be cleared when navigating up/down the list with keyboard
- **Tabs**: Fixed issue where tabs with links should not trigger tab change upon cmd/middle click
- **Menu**: Fixed issue where `Menu.ItemText` could not be used with `Menu.Item`
## [5.13.0] - 2025-06-07
### Added
- **Collection**: Add new `useListCollection` hook to create a dynamic list collection.
### Fixed
- **Progress**: Export `ProgressValueChangeDetails` and `ProgressValueTranslationDetails` types from `@zag-js/progress`
## [5.12.0] - 2025-06-05
### Added
- **Tree View**: Add support for lazy loading node children. To use this, you need to provide:
- `loadChildren` is a function that is used to load the children of a node.
- `onLoadChildrenComplete` is a callback that is called when the children of a node are loaded. Used to update the
tree collection.
- Add `childrenCount` to the node object to indicate the number of children.
### Fixed
- **Slider**
- Fixed issue where `Shift` + `ArrowRight` set value to `0` instead of `max` when step is too large (e.g. `20`)
- Fixed issue where `onValueChangeEnd` doesn't return the latest value when dragging very fast
## [5.11.0] - 2025-05-30
### Added
- **File Upload**: Added support for transforming uploaded files via `transformFiles` context property.
### Fixed
- **Slider**: Fixed issue where `minStepsBetweenThumbs` isn't computed correctly when interacting with pointer or
keyboard.
## [5.10.0] - 2025-05-29
### Added
- **[NEW] Password Input**: Added `PasswordInput` component for collecting secure text inputs.
```tsx
import { PasswordInput } from '@ark-ui/vue/password-input'
import { EyeIcon, EyeOffIcon } from 'lucide-vue-next'
export const Basic = () => (
Password }> )` with a step id doesn't work as expected - **Menu**: Fix issue where `Menu.Item` throws a `document is not defined` error when used in a Nuxt app. ## [5.9.1] - 2025-05-12 ### Fixed - **Combobox** - Fixed issue where `focusable` prop was not being applied to the trigger element. - Fixed issue where combobox doesn't work for items rendered as links. - **Collection**: Fix issue where `getNextValue` and `getPreviousValue` doesn't work as expected when `groupBy` is used. ## [5.9.0] - 2025-05-05 ### Added - **Locale**: Added `useFilter` composable to filter data based on the current locale. - **Format**: Added `FormatRelativeTime` component for formatting relative time. ## [5.8.0] - 2025-05-01 ### Added - **Date Picker**: Added support for `outsideDaySelectable` prop to allow selecting days outside the current month (on the same visible date range) ## [5.7.0] - 2025-04-25 ### Added - **[NEW] Listbox**: Introduced the `Listbox` component for selecting a single or multiple items from a list. See the [documentation](https://ark-ui.com/docs/components/listbox) for details. - Improved support for grouping collection items. Check the `Listbox`, `Select` or `Combobox` documentation for more details. ### Changed - Added `package.json` to `exports` for improved compatibility with tools like Vite. ## [5.6.0] - 2025-04-15 ### Added - **[NEW] AngleSlider**: Introduced the `AngleSlider` component for selecting an angle. See the [documentation](https://ark-ui.com/docs/components/angle-slider) for details. - **[NEW] FloatingPanel**: Introduced the `FloatingPanel` component for creating floating windows. See the [documentation](https://ark-ui.com/docs/components/floating-panel) for details. - **Toast**: Added toast queuing when the max limit is reached: - New toasts were queued instead of dropped - Queued toasts were shown when space became available - Queue cleared when all toasts were removed - **Combobox**: - Fallbacked to the trigger element as the positioning anchor - Added `data-empty` attribute to indicate an empty listbox or content ### Fixed - **CheckboxGroup**: Fixed issue where `v-model` doesn't work as expected. ## [5.5.0] - 2025-04-05 ### Added - **Presence**: Added support for skipping the initial animation when the component is mounted. This can be used in all disclosure components (e.g., `Dialog`, `DatePicker`, `Menu` etc). ### Fixed - **Tabs**: Fixed issue where tabs indicator animation behaves inconsistently. - **Date Picker** - Fixed issue where datepicker throws error when navigating month view. - Fixed issue where range selection doesn't reset correctly when clicking the same start date. - **Disclosure Components** - Fixed issue where pointerdown outside doesn't work consistently on mobile devices. - Improved pointerdown outside click detection in shadow DOM environments. ## [5.4.0] - 2025-03-28 ### Added - **Slider** - Add support for `origin: end` to align the thumb to the end of the track. - Expose `thumbSize` as CSS variables in the root element. Can be useful for styling the slider. - **Menu** - Added `select` emit event to the `Menu.Item` component. ### Fixed - Ensured each component's state machine starts before processing events. - **HoverCard, ColorPicker**: Added missing `tabIndex` for better dialog support. - **Menu**: Assigned unique IDs to menu items to improve accessibility and HTML validation. - **Field**: Fixed `Textarea` to use `ark.textarea`, ensuring support for the `asChild` prop. ## [5.3.0] - 2025-03-24 ### Added - **Collapsible**: Added an `Indicator` part to display whether the collapsible was open or closed. - **ColorPicker**: Added support for formatting the `ValueText` component. ```tsx // #ff0000 ``` ### Fixed - **Combobox**: Fixed an issue where `onOpenChange` was called with the same `open` value. - **Splitter**: Fixed an issue where `onResizeStart` and `onResizeEnd` callbacks weren't triggered during keyboard interactions. ## [5.2.0] - 2025-03-22 ### Added - **[NEW] DownloadTrigger**: Added Component for downloading a blob or file, whether retrieved synchronously or asynchronously. ```tsx import { DownloadTrigger } from '@ark-ui/react/download-trigger' export const DownloadImage = () => { async function fetchImage() { const response = await fetch('https://picsum.photos/200/300') return response.blob() } return ( Download Image ) } ``` ### Changed - **NumberInput**: Set the default step to `0.01` when `formatOptions.style` was set to `percent`. - **[Breaking] Splitter**: Redesigned splitter machine to support more use cases and improve DX. Check out the [Splitter](https://ark-ui.com/docs/components/splitter) documentation for more details. ### Fixed - **Toast**: Fixed issue where setting `offsets` to `undefined` caused the machine to throw. - **Select**: Fixed issue where select `valueAsString` lost reactivity. ## [5.1.1] - 2025-03-17 ### Fixed - **Field**: Exported the missing `useField` hook. - **NumberInput**: `onValueChange` correctly received `valueAsNumber`. - **Slider**: Thumbs initialized correctly when `min` was set to a non-zero value. ## [5.1.0] - 2025-03-11 ### Added - Implemented support for reactive props in `use-*.ts` functions. ```tsx const value = ref(['React']) const accordionProps = computed(() => ({ multiple: true, value: value.value, onValueChange: (e) => (value.value = e.value), })) const accordion = useAccordion(accordionProps) ``` ### Fixed - **Checkbox**: `data-invalid` is no longer set when `invalid` is `false`. - **Combobox**: Fixed unexpected cursor movement when editing input. - **PinInput**: OTP SMS autofill now works as expected. - **RatingGroup**: Fixed incorrect focus placement on the label. - **TagsInput**: Improved caret detection to prevent unintended tag removal. - **Timer** - Fixed slowdown when switching tabs/windows. - Changed default `interval` from `250` to `1000`. ## [5.0.2] - 2025-03-06 ### Fixed - **Steps**: Fixed issue where `Steps.X` namespace was not exported. ## [5.0.1] - 2025-03-06 Ark UI just got a major performance boost! 🚀 ### What’s new in v5? - **Blazing-fast performance** – Every component runs smoother and renders faster. - **Smaller bundle size** – Leaner components and adapters for a more efficient build. We made this happen by using Vue's native reactive primitives instead of external stores. In our stress tests with **10,000 components**, Ark v5 delivered **1.5x–4x** better performance across the board. ### A quick note on tests Most component updates are non-breaking, but due to this change, some tests may need adjustments. For example: ```jsx // Before it('should open by default', () => { render(ComponentUnderTest, { props: { defaultOpen: true, }, }) expect(screen.getByRole('dialog')).toBeInTheDocument() }) // After it('should open by default', async () => { render(ComponentUnderTest, { props: { defaultOpen: true, }, }) expect(await screen.findByRole('dialog')).toBeInTheDocument() }) ``` #### Added - **Carousel**: ⚠️ Breaking change: Added required prop `slideCount` to `Carousel.Root` component. - **Clipboard**: Added `onValueChange` and `defaultValue` props. - **ColorPicker**: Added `defaultFormat` prop. - **Combobox**: Added `defaultHighlightedValue` and `defaultInputValue` props. - **DatePicker**: Added `defaultFocusedValue` prop, `getViewProps`, and `visibleRangeText`. - **HoverCard**: Expanded interaction handlers. - **Menu**: Added `defaultHighlightedValue` prop. - **Pagination**: Added `defaultPageSize` prop. - **PinInput**: Added `count` prop for better SSR aria-label. - **Progress**: Added `locale` and `formatOptions` props. - **QrCode**: Added `pixelSize` prop. - **Select**: Added `defaultHighlightedValue` prop. - **TagsInput**: Added `defaultInputValue` prop. - **Toggle**: Reintroduced toggle machine. #### Fixed - **Accordion**: Fixed issue in Safari where clicking triggers didn't show content. - **Avatar**: Fixed `api.setSrc` not working. - **Carousel**: Fixed pagination sync and initial page issues. - **File Upload**: Fixed drag-and-drop when `directory: true`. - **Menu**: Fixed context menu positioning not updating on right-click. - **Number Input**: Fixed `value` prop not being consumed. - **Pin Input**: Fixed focus warnings and editing issues. - **Progress**: Allowed more precise (decimal) values. - **Radio Group, Switch**: Improved focus behavior in Safari. - **Select**: Fixed regression where `multiple: true` didn't work. - **Steps**: Ensured ARIA attributes use valid values and wrapped ` - ` elements correctly within `
- `.
- **Textarea**: Fixed `ResizeObserver` warning.
- **Timer**: Fixed stopping issue when switching tabs; resolved issue where `action` prop was passed to `ActionTrigger`.
- **Toast**: Fixed keyboard navigation skipping close button.
- **Toggle Group**: Fixed `data-focus` not being removed on blur.
# Changelog
## [Unreleased]
## [5.15.0] - 2025-12-10
### Added
- **Date Picker**: Added `required` and `invalid` props
- **Number Input**: Added `onValueCommit` callback that fires when the input loses focus or Enter is pressed
- **Pagination**:
- Added `FirstTrigger` and `LastTrigger` components for navigating to first/last page
- Added `boundaryCount` parameter for controlling boundary pages (start/end)
- Implemented balanced pagination algorithm for consistent UI with max 7 elements
- **Radio Group**: Added `invalid` and `required` props with corresponding `data-*` and `aria-*` attributes
- **Tree View**: Added `scrollToIndexFn` prop to enable keyboard navigation in virtualized trees
### Fixed
- **Accordion, Menu**: Fixed issue where querying elements by `aria-controls` attribute could fail when lazy mounting the content
- **Color Picker**: Added `role="dialog"` to content and `aria-haspopup="dialog"` to trigger when not inline for better accessibility
- **Date Picker**: Fixed issue where date picker input does not update format when locale changes
- **Floating Panel**:
- Fixed `dir` prop now properly delegated to all panel parts
- Fixed double-click behavior improvements and to check `event.defaultPrevented` for custom behavior
- **Listbox**:
- Fixed issue where `data-highlighted` wasn't applied to the first item when using `autoHighlight` with input filtering
- **Number Input**:
- Fixed issue where input element doesn't sync when `formatOptions` changes dynamically
- Ensured cursor position is preserved when `Enter` key is pressed and formatting is triggered
- Fixed cursor jumping to start when value is changed externally via props while user is typing
- **Pagination**: Fixed ellipsis showing when only 1 page gap
- **Rating Group**: Fixed issue where rating group becomes unfocusable via keyboard when value is 0
- **Tooltip**: Fixed tooltip not showing when scrolling with pointer over trigger
- **Collapsible, Presence, Tour**: Fixed machines setting reactive state in unmount lifecycle
### Changed
- **Tree View**: `getVisibleNodes()` now returns `{ node, indexPath }[]` instead of `node[]`
## [5.14.1] - 2025-11-22
### Fixed
- **Floating Panel**:
- Fixed resize trigger issue with `n` axis by explicitly setting `top: 0`
- Fixed `draggable` and `resizable` options not being respected when set to `false`
- **Presence**: Fixed regression where UNMOUNT transition might not be called consistently
## [5.14.0] - 2025-11-20
### Added
- **Carousel, Color Picker, Combobox, Date Picker, Select**: Added `value` to `OpenChangeDetails` for better context
when handling open state changes
- **Carousel**: Added support for `autoSize` prop to allow variable width/height slide items
- **Splitter**:
- Added `Splitter.ResizeTriggerIndicator` to render an indicator when resizing
- Exported `getLayout` and `getSplitterLayout` functions for calculating splitter panel layouts
- **Toast**: Exposed viewport offset as CSS variables on the toast group element
### Fixed
- **Carousel**:
- Fixed dragging behavior that stops working after switching browser tabs or scrolling the page
- Fixed dragging not working after scrolling with mouse wheel when `allowMouseDrag` is enabled
- **Combobox**: Fixed `onHighlightChange` not being invoked when collection is filtered to empty
- **Date Picker**: Fixed issue where the range date picker crashes when typing the end date first and blurring the input
field multiple times
- **File Upload**: Fixed issue where clicking on non-interactive children inside the dropzone doesn't open the file
picker
- **Presence**: Fixed a bug where elements get stuck in unmountSuspended state during rapid state updates
- **Radio Group**:
- Fixed inconsistent application of `data-focus-visible` and `data-focus` attributes
- **Splitter**: Fixed disabled splitter showing resize cursor and allowing dragging
- **Tabs**:
- Fixed tabs indicator position not updating when inactive tabs change size
- **Tags Input**: Fixed issue where item delete trigger doesn't have `data-*` attached
## [5.13.0] - 2025-11-14
### Added
- **General**: Exported `InteractOutsideEvent`, `FocusOutsideEvent`, and `PointerDownOutsideEvent` types for better type
safety
- **Carousel**:
- Added `Carousel.AutoplayIndicator` component for conditionally rendering content based on autoplay state
- Added `Carousel.ProgressText` component for displaying current page progress (e.g., "1 / 5")
- **Toast**: Exported `ToastOptions` and `ToastStoreProps` types for better type safety
### Changed
- **useListCollection**: Updated `initialItems` to accept `readonly` arrays for better compatibility with immutable data
patterns.
### Fixed
- **Slider**:
- Fixed `Slider.ValueText` not displaying default value when no children provided
- Fixed `SliderThumbPropsProvider` to use modern Svelte 5 runes (`$props()` and `{@render children?.()}`)
- **Combobox**:
- Fixed focus stealing in controlled open mode
- Removed problematic `aria-hidden` behavior to allow interaction with other page elements
## [5.12.1] - 2025-11-02
### Fixed
- **Dialog, Popover**: Improved shadow DOM support for interact outside and focus trap detection
- **Marquee**: Fixed Firefox flicker and added GPU acceleration
- **Dialog**: Fixed layout shift issue when using `scrollbar-gutter: stable` in CSS
- **Slider**: Fixed `onValueChangeEnd` callback not triggering for programmatic value changes
## [5.12.0] - 2025-11-01
### Added
- **Marquee** [New]: Initial release of marquee component for continuously scrolling content
### Fixed
- **Angle Slider**: Resolved an issue where dragging the thumb from non-center positions caused unexpected value jumps.
The thumb now maintains consistent positioning relative to the initial click point.
- **Slider**: Fixed a problem where the thumb offset shifted dynamically during dragging, resulting in value jumps. The
offset now remains constant from the pointer throughout the drag operation.
- **Svelte**: Refactored `mergeProps` to return class values as arrays, delegating resolution to Svelte's native class
handling for improved support of conditional classes and objects.
- **Date Picker**: Resolved a crash in the range date picker occurring when users typed the end date first by
implementing `null`/`undefined` checks for date property access.
- **Radio Group**: Reverted to `offsetLeft`/`offsetTop` calculations to restore correct indicator positioning within
scrollable container contexts.
- **Tabs**: Reverted to `offsetLeft`/`offsetTop` calculations to fix indicator positioning issues in scrollable
containers.
- **Tour**:
- Corrected improper effect cleanup procedures
- Fixed wait step functionality
- Added step validation on mount to verify configuration validity
## [5.11.2] - 2025-10-18
### Fixed
- **Angle Slider**: Fix accessibility violation where the slider thumb element lacked an accessible name. The thumb now
supports `aria-label` and `aria-labelledby` props, and automatically falls back to the label element's ID for proper
ARIA labeling.
- **Select**: Fix accessibility violation where the required state was not set correctly to on the trigger.
- **Tags Input**: Fix issue where entering a custom tag with combobox integration required pressing `Enter` twice. The
tags-input now correctly handles custom values when the combobox has no highlighted item (`aria-activedescendant` is
empty), allowing the tag to be added on the first `Enter` press.
## [5.11.1] - 2025-10-15
### Fixed
- **Checkbox**
- Fix issue where setting initial checked state to `indeterminate` doesn't work
- Ensure `api.checkedState` returns the correct checked state (`boolean | "indeterminate"`)
- **Collapsible**: Fix issue where `dir` prop value was hardcoded to `ltr` instead of using the provided value
- **Combobox**: Fix issue where controlled single-select combobox does not propagate its initial value to `inputValue`
- **Listbox**: Fix issue where pressing Enter key when no highlighted item still calls `event.preventDefault()`
- **Radio Group**: Refactor to use `getBoundingClientRect()` for precise indicator positioning
- **Slider**
- Fix issue where slider could stop abruptly when scrubbing thumb
- Fix issue where range slider thumbs become stuck when dragged to the same position without `minStepsBetweenThumbs`
- **Tabs**: Refactor to use `getBoundingClientRect()` for precise indicator positioning
- **Tags Input**: Fix issue where `maxLength` doesn't apply to the edit input as well
## [5.11.0] - 2025-10-08
### Added
- **Collapsible**: Add support for `collapsedHeight` and `collapsedWidth` props to control the dimensions of the
collapsible content when in its collapsed state.
- **Focus Trap**: Allow elements referenced by `aria-controls` to be included in the trap scope. This makes it possible
for menus, popovers, etc. to be portalled and work correctly.
- **Pagination**: Add `getPageUrl` prop for generating `href` attributes when using pagination as links.
```ts
const service = useMachine(pagination.machine, {
type: 'link',
getPageUrl: ({ page, pageSize }) => `/products?page=${page}&size=${pageSize}`,
})
```
- **Select**: Add `SelectRootComponentProps` type export for better component type composition.
- **Listbox**: Add `ListboxRootComponentProps` type export for better component type composition.
- **Combobox**: Add `ComboboxRootComponentProps` type export for better component type composition.
- **TreeView**:
- Add `TreeViewRootComponentProps` type export for better component type composition.
- (Experimental) Add support for node renaming functionality:
- Add `TreeViewNodeRenameInput` component for inline node label editing
- Add `canRename` prop to control which nodes can be renamed
- Add `onRenameStart`, `onBeforeRename`, and `onRenameComplete` callbacks for rename lifecycle
- Add `CheckedChangeDetails`, `LoadChildrenErrorDetails`, `RenameStartDetails`, and `RenameCompleteDetails` type
exports
### Fixed
- **Select**: Fix issue where `Select.HiddenSelect` doesn't emit correct values when using custom objects with
`itemToValue`
- **Field**: Fix issue where `bind:value` doesn't work correctly in `Field.Textarea`, `Field.Input`, and `Field.Select`
components
- **Password Input**: Fix issue where `bind:value` doesn't work correctly in `PasswordInput.Input` component
- **Scroll Area**: Fix RTL horizontal scrollbar positioning on Safari
- **Slider**: Fix issue where slider continues dragging when disabled during drag operation.
- **Switch**: Fix issue where `data-active` is inconsistently applied when `disabled` state changes at runtime
- **Presence**: Fix issue where exit animations don't work on subsequent toggles when using `lazyMount` and
`unmountOnExit` together
## [5.10.1] - 2025-09-27
### Fixed
- **Date Picker**
- Fix issue where year range picker doesn't show the hovered range
- Fix issue where quarter presets returns incorrect date
- **FormatByte**: Add support for `unitSystem` property to allow changing between decimal (1000 bytes) and binary (1024
bytes) systems.
- **Number Input**: When `formatOptions` is used (like `style: "currency"`), the cursor would jump to the end of the
input when typing in the middle. The cursor now maintains its relative position during formatting changes.
- **Pin Input**: Fix issue where using the keyboard shortcuts `Cmd+Backspace` and `Cmd+Delete` to delete text in pin
inputs would insert "undefined" instead of clearing the field.
- **Scroll Area**: Fix issue where resize tracking was not observing the root element, which caused the scrollbar to not
update when the root element's size changed.
- **Select**: Fix inconsistent `lazyMount`/`unmountOnExit` behavior where the positioner remained in the DOM when the
component was closed, while the content was correctly unmounted.
- **Exports**: Fix issue where Node.js programs like PandaCSS were not able to resolve the `@ark-ui/svelte/anatomy`
entrypoint due to the missing `default` condition
## [5.10.0] - 2025-09-17
### Added
- Added `mergeProps` utility for combining multiple props objects with proper event handler and className merging.
- Added `createContext` utility for creating typed React contexts with improved DX.
```tsx
import { createContext } from '@ark-ui/solid/utils'
```
## [5.9.1] - 2025-09-14
### Fixed
- **General**: Fix issue where `mergeProps` throws when `props` is `undefined` or `null`
## [5.9.0] - 2025-09-14
### Removed
- **TimePicker**: The TimePicker component has been removed from this release. This component was never part of the
public API and was considered experimental. It had significant bugs and usability issues across all frameworks and
locales, making it unsuitable for production use.
**Migration**: We recommend building a custom time picker using the Select component for simple use cases, or
implementing a time grid pattern for more complex scenarios.
### Added
- **Combobox**: Add `alwaysSubmitOnEnter` prop to allow bypassing the default two-step behavior (Enter to close
combobox, then Enter to submit form) and instead submit the form immediately on Enter press. This is useful for
single-field autocomplete forms where Enter should submit the form directly.
- **Dismissable**: Add support for layer types in dismissable layer stack. Layers can now be categorized as `dialog`,
`popover`, `menu`, or `listbox`. This enables:
- `data-nested` attribute on nested layers of the same type
- `data-has-nested` attribute on parent layers with nested children of the same type
- `--nested-layer-count` CSS variable indicating the number of nested layers of the same type
### Changed
- **Hover Card**: Change default delay values for hover card to improve accessibility.
- `openDelay`: from `700ms` to `600ms`
- **Tooltip**: Change default delay values for tooltip to improve accessibility.
[Learn more](https://www.nngroup.com/articles/timing-exposing-content)
- `openDelay`: from `1000ms` to `400ms`
- `closeDelay`: from `500ms` to `150ms`
### Fixed
- **Editable**: Allow text selection in editable preview when `autoResize` is enabled
Previously, when `autoResize` was set to `true`, the preview element had `userSelect: "none"` applied, preventing
users from selecting text. This has been fixed by removing the `userSelect` style property.
- **File Upload**: Fix regression where clicking the trigger doesn't open the file picker when used within the dropzone
- **Svelte**: Fix Svelte warning about state reference capturing initial value instead of current reactive state
- **Menu**
- Fix issue where hovering a partially visible item with pointer causes it to scroll into view
- Fix issue where keyboard activation of menu items with `target="_blank"` would open two tabs
- **Tabs**: Fix issue where `ids` for `item` and `content` could not be customized
- **Toast**: Allow creating a toast store without any arguments
## [5.8.0] - 2025-09-08
### Added
- **Field**: Add `data-required` attribute to `Field.Label`
- **Select, Combobox, Listbox, TreeView**: Export `RootComponent` and `RootProviderComponent` types which are useful
when building compositions that wrap the `Root` and `RootProvider` components and you still want type-safety for the
collection.
### Fixed
- **Menu**: Fix `Menu.ItemText` not working inside `Menu.TriggerItem`
## [5.7.0] - 2025-08-28
### Added
- **Combobox**: Add `ComboboxEmpty` component to display content when the combobox has no items
- **Listbox**: Add `ListboxEmpty` component to display content when the listbox has no items
- **Hover Card**: Add support for `disabled` prop
### Fixed
- **Collection**: Fix issue where disabled items could be reached via typeahead
- **Color Picker**: Fix issue where color picker was not working correctly in RTL mode
- **Date Picker**: Fix issue where datepicker doesn't revert to a valid value when the input value exceeds the min/max
and blurred
- **Dismissable**: Expose `onRequestDismiss` custom event handler for event a parent layer requests the child layer to
dismiss. If prevented via `event.preventDefault()`, the child layer will not dismiss when the parent layer is
dismissed.
- **Number Input**
- Omit the input `pattern` when `formatOptions` is provided. This prevents native pattern validation from conflicting
with formatted values (e.g., currency or percent).
- Handle empty values consistently across all format options.
- Add `data-scrubbing` attribute to the number input parts.
- **Tags Input**: Fix issue where highlighted item doesn't clear when tabbing out of the input to an external button
within the `control` part.
- **Tooltip**
- Set `closeOnPointerdown` to `false` when `closeOnClick` is set to `false`
- Reduce bundle size by replacing `@zag-js/store` dependency with a lightweight store implementation.
## [5.6.0] - 2025-08-24
### Added
- **Functions**: Add `useAsyncList` and `useCollator` functions for managing asynchronous list operations and
locale-aware string comparison
- **Toast**: Export type definitions `ToastActionOptions`, `ToastPlacement`, `ToastPromiseOptions`, `ToastStatus`,
`ToastStatusChangeDetails`, and `ToastType`
### Changed
- **Fieldset**
- Update Legend component to render as `div` instead of `legend` element for improved styling flexibility
- Add `aria-labelledby` attribute to fieldset root for better accessibility by linking to legend
### Fixed
- **Date Picker**
- Clear hovered range state after completing range selection instead of waiting for pointer to leave the calendar
area.
- Fix issue where month and year select labels don't update correctly when using `min`/`max` constraints.
- Expose `disabled` on `api.getMonths()` and `api.getYears()` results to indicate options out of range for current
constraints.
- **Listbox**
- Fix issue where first enabled item should be highlighted by default when listbox receives focus and no item is
currently highlighted.
- Add `getElement` to `scrollToIndexFn` details
- Track collection changes and clear `highlightedValue` if the item is no longer in the collection.
- **ScrollArea**
- Avoid detecting hover state from portalled descendants.
- Add `data-dragging` attribute to scroll area parts.
- **Select**: Add `getElement` to `scrollToIndexFn` details
- **Combobox**: Add `getElement` to `scrollToIndexFn` details
## [5.5.0] - 2025-08-20
### Added
- **Highlight Word**: Add `exactMatch` option that enables whole-word matching using regex word boundaries.
### Fixed
- **Menu**: Fix context menu repositioning logic
- **Scroll Area**: Add `data-hover` to scroll area
## [5.4.0] - 2025-08-18
### Added
- **ScrollArea [NEW]**: Add support for new scroll area component.
### Fixed
- **ListCollection**
- Avoid recomputing groups on every call to `at()` and `indexOf()`
- Fixed bug in `find()` method (was checking `!= null` instead of `!== -1`)
- **GridCollection**: Avoid recomputing rows on every call to `getRows()`
- **Menu**
- Add `data-state` attribute for context menu trigger
- Fix context menu positioning bug where reopening at the same coordinates fails to reposition
## [5.3.4] - 2025-08-14
### Fixed
- **Listbox**: Add support for navigating grid collections
- **Carousel**:
- Fix an issue where the carousel would not update when `slideCount` or `autoplay` props change.
- Fix an issue where `loop: false` was ignored when using autoplay. Now, the carousel will stop when it gets to the
last slide.
- **Date Picker**: Expose `data-inline` attribute on Content part to enable distinct styling for inline date pickers
versus popover date pickers.
- **Menu**: Fix issue where `onCheckedChange` could be called twice on checkbox or radio item
- **Radio Group**: Fixed issue where arrow key navigation doesn't apply `data-focus-visible` on the newly focused item.
- **TagsInput**: Export `InputValueChangeDetails` type
### Changed
- **Async List**: Improve type inference for descriptors
- **Framework Components**: Improve runtime performance of components
## [5.3.3] - 2025-08-01
### Fixed
- **Carousel**: Fix issue where controlled carousel ignores last slide
## [5.3.2] - 2025-07-26
### Fixed
- **Dialog**
- Sync content `--layer-index` with positioner and backdrop
- Decouple `trapFocus` from `modal` so it's possible to set `modal=false` and `trapFocus=true`
## [5.3.1] - 2025-07-23
### Fixed
- **Date Picker**: Fixed issue where hovered range was connect to selected values, when it shouldn't
- **Tree View**: Fixed issue where tree view doesn't scroll into view when content overflows.
- **Portal**: Fix issue in SvelteKit where `Portal` component doesn't work as expected.
## [5.3.0] - 2025-07-22
### Added
- **Collection**: Add `useListSelection` function for managing collection item selection with support for
single/multiple selection modes
```js
const collection = createListCollection({ items: ['React', 'Vue', 'Angular'] })
const selection = useListSelection({ collection })
// Check if item is selected
const isSelected = selection.isSelected('Svelte')
// Select/deselect items
selection.select('Svelte')
selection.toggle('Angular')
```
- **File Upload**: Add support for `bind:acceptedFiles` and `defaultAcceptedFiles` to programmatically control the
accepted files
- **Signature Pad**: Add support for `bind:paths` and `defaultPaths` to programmatically control the paths
- **Date Picker**: Added hover range preview support for date picker range selection. Added `inHoveredRange`,
`firstInHoveredRange`, and `lastInHoveredRange` properties to `DayTableCellState` with corresponding data attributes
`data-in-hover-range`, `data-hover-range-start`, and `data-hover-range-end`.
Hover range states are only active when not overlapping with actual selected range, enabling distinct styling for
hover preview vs actual selection in range mode.
### Fixed
- **Date Picker**: Fix date comparison issues when time components are involved. This resolves critical issues with date
comparison operations when different date types (`CalendarDate`, `CalendarDateTime`, `ZonedDateTime`) are mixed,
particularly in scenarios involving time components.
## [5.2.0] - 2025-07-18
### Added
- **Checkbox**: Add `CheckboxGroupProvider` component for external checkbox group state management
### Fixed
- **Carousel**: Fix issue where full page carousel could trap scrolling
- **ListCollection**: Export `UseListCollectionReturn` type
- **TreeCollection**: Fix issue where the `filter` method completely deletes the children key from the node when there
are no matching children
- **Number Input**: Fix issue where default pattern does not allow negative numbers with decimal point
- **File Upload**
- Export `FileError`, `FileMimeType`, and `FileRejection` types
- Fix issue where calling `api.setFiles` invokes validation with incorrect `acceptedFiles`
- Fix issue where the browser might not be able to infer the mime type of a file due to limitations, drag source or
security restrictions. As a fallback in the file validation logic, we now infer the mime type from the file
extension.
- **Portal**: Fix issue where `lifecycle_double_unmount` warning could be triggered.
## [5.1.1] - 2025-07-05
### Fixed
- **Combobox**
- Expose `reason` to `onOpenChange` and `onInputValueChange` callbacks
- Expose `api.clearHighlightedValue` function to clear highlighted value
- **Date Picker**
- Fix issue where datepicker errors when setting `selectionMode=range` and `minView=year`
- Fix issue where `focusedValue` could not be fully controlled
- **Listbox**: Select highlighted item only if it exists in the collection
- **Progress**: Improve `valueAsString` formatting
- **Select**
- Select highlighted item only if it exists in the collection
- Expose `api.clearHighlightedValue` function to clear highlighted value
- **Tour**: Fix an issue where the `goto` function in `StepActionMap` doesn't work when passing step IDs (string)
- **Tree View**: Expose `id` in the tree node state
## [5.1.0] - 2025-07-01
### Added
- **Angle Slider [New]**: Add support for angle slider component for angle selection.
- **Color Picker**: Add support for `inline` prop to render color picker inline
- **Date Picker**: Add support for `inline` prop to render the date calendar inline
### Fixed
- **Color Picker**: Auto-prefix Hex values with `#` if missing when using the `hex` channel input
- **Menu**: Fix interaction outside detection for focusable context trigger
- **Tree View**: Improve support for rendering tree items as links
## [5.0.5] - 2025-06-28
### Fixed
- Fix issue where `bind:ref` doesn't work with components, making it impossible to access the underlying DOM element.
Now, you can pass `bind:ref` to all components.
```svelte