- ` or `
- ` elements correctly within `
- ` or `
- ` elements correctly within `
- ` or `
- `.
- **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).
# LLMs.txt
## What is LLMs.txt?
We support [LLMs.txt](https://llmstxt.org/) files for making the Ark UI documentation available to large language models
(LLMs). This feature helps AI tools better understand our component library, its APIs, and usage patterns.
## Available Routes
We provide several LLMs.txt routes to help AI tools access our documentation:
- [llms.txt](https://ark-ui.com/llms.txt) - Contains a structured overview of all components and their documentation
links
- [llms-full.txt](https://ark-ui.com/llms-full.txt) - Provides comprehensive documentation including implementation
details and examples
- [llms-react.txt](https://ark-ui.com/llms-react.txt) - React-specific documentation and implementation details
- [llms-solid.txt](https://ark-ui.com/llms-solid.txt) - SolidJS-specific documentation and implementation details
- [llms-vue.txt](https://ark-ui.com/llms-vue.txt) - Vue-specific documentation and implementation details
- [llms-svelte.txt](https://ark-ui.com/llms-svelte.txt) - Svelte-specific documentation and implementation details
## Usage with AI Tools
### Cursor
Use the `@Docs` feature in Cursor to include the LLMs.txt files in your project. This helps Cursor provide more accurate
code suggestions and documentation for Ark UI components.
[Read more about @Docs in Cursor](https://docs.cursor.com/context/@-symbols/@-docs)
### Windstatic
Reference the LLMs.txt files using `@` or in your `.windsurfrules` files to enhance Windstatic's understanding of Ark UI
components.
[Read more about Windstatic Memories](https://docs.codeium.com/windsurf/memories#memories-and-rules)
### Other AI Tools
Any AI tool that supports LLMs.txt can use these routes to better understand Ark UI. Simply point your tool to any of
the routes above based on your framework of choice.
# 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:
```vue
{{ getInitials }} ``` # Collection Collections are used to manage a collection of some kind, like menus, select, combobox, etc. They provide functionalities such as sorting, searching, getting next or previous items, converting items to values or strings, checking if an item is disabled, and more. ## List Collection A list collection is a collection that is based on an array of items. It is created by passing an array of items to the constructor. ```ts import { createListCollection } from '@ark-ui/react/collection' const collection = createListCollection({ items: [ { label: 'Apple', value: 'apple' }, { label: 'Banana', value: 'banana' }, ], }) console.log(collection.items) // [{ label: 'Apple', value: 'apple' }, { label: 'Banana', value: 'banana' }] ``` ### Converting value to item Use the `find` or `findMany` method to convert a value to an item. ```ts const item = collection.find('banana') console.log(item) // { label: "Banana", value: "banana" } const items = collection.findMany(['apple', 'banana']) console.log(items) // [{ label: "Apple", value: "apple" }, { label: "Banana", value: "banana" }] ``` ### Value Traversal Use the `getNextValue` or `getPreviousValue` method to get the next or previous item based on a value. ```ts const nextValue = collection.getNextValue('apple') console.log(nextValue) // banana const previousItem = collection.getPreviousValue('banana') console.log(previousItem) // apple ``` Likewise, use the `firstValue` or `lastValue` computed properties to get the first or last item. ```ts console.log(collection.firstValue) // apple console.log(collection.lastValue) // banana ``` ### Check for value existence Use the `has` method to check if a value exists in the collection. ```ts const hasValue = collection.has('apple') console.log(hasValue) // true ``` ### Working with custom objects If you are working with custom objects, you can pass a function to the `itemToString` and `itemToValue` options to specify how to convert an item to a string and a value, respectively. > By default, we look for the `label` and `value` properties in the item. ```ts import { createListCollection } from '@ark-ui/react/collection' const collection = createListCollection({ items: [ { id: 1, name: 'apple' }, { id: 2, name: 'banana' }, { id: 3, name: 'cherry' }, ], itemToString: (item) => item.name, itemToValue: (item) => item.id, }) ``` To mark an item as disabled, pass a function to the `isItemDisabled` option. > By default, we look for the `disabled` property in the item. ```ts import { createListCollection } from '@ark-ui/react/collection' const collection = createListCollection({ items: [ { id: 1, name: 'apple' }, { id: 2, name: 'banana' }, { id: 3, name: 'cherry' }, ], isItemDisabled: (item) => item.id === 2, }) ``` ### Reorder items Use the `reorder` method to reorder items by passing the starting index and the ending index of the item to be moved. ```ts const fromIndex = 1 // Banana const toIndex = 0 // Apple collection.reorder(fromIndex, toIndex) console.log(collection.items) // [{ label: "Banana", value: "banana" }, { label: "Apple", value: "apple" }] ``` ## 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. # Component State ## Context Components Context components expose state and functions to child components. In this example, `Avatar.Fallback` renders based on `loaded` state. ```vue {{ avatar.loaded ? 'PA' : 'Loading' }} What is {{ item }}? {{ item }} is a JavaScript library for building user interfaces. Ark UI (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{/* … */} {/* … */} {/* … */} What is {{ item }}? {{ item }} is a JavaScript library for building user interfaces. What is {{ item }}? {{ item }} is a JavaScript library for building user interfaces. What is {{ item }}? {{ item }} is a JavaScript library for building user interfaces. What is {{ item }}? {{ item }} is a JavaScript library for building user interfaces. What is {{ item }}? {{ item }} is a JavaScript library for building user interfaces. What is {{ item }}? {{ 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. ` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. **`lazyMount`** Type: `boolean` Required: false Default Value: `false` Description: Whether to enable lazy mounting **`unmountOnExit`** Type: `boolean` Required: false Default Value: `false` Description: Whether to unmount on exit. ## 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. ```vue Wind direction Temperature {{ angle }} ºC ` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### Thumb #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`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 **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. # 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: ```vue PA PA PA ) } const Demo = () => { return (
JD ` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. # 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: ```vue Previous Next Previous Next Current page: {{ page }}
``` ### Autoplay The Carousel can play automatically. Just add the `autoplay` prop. You'll probably want to add `loop` too, so it keeps going after the last slide. ```vue{{ context.isPlaying ? 'Pause' : 'Play' }} Previous Next ` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ## 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: ```vue Checkbox Checkbox Checkbox {{ item.label }} Checkbox {{ checkbox.checked.toString() }} Label Additional Info Error Info Checkbox ` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ## 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: ```vue Copy this link Copy this link ` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### Trigger #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: clipboard **`data-part`**: trigger **`data-copied`**: Present when copied state is true ### ValueText #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. # 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 ```vue Toggle Content Toggle Content Toggle Content Toggle Content Toggle Content Toggle Content Color Toggle ColorFormat ✓ ✓ ✓ Pick color Color ✓ ✓ ✓ Pick color Label Additional Info Error Info Color Toggle ColorFormat ✓ ✓ ✓ Pick color ` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. **`lazyMount`** Type: `boolean` Required: false Default Value: `false` Description: Whether to enable lazy mounting **`unmountOnExit`** Type: `boolean` Required: false Default Value: `false` Description: Whether to unmount on exit. ### SwatchGroup #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### SwatchIndicator #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### Swatch #### Props **`value`** Type: `string | Color` Required: true Default Value: `undefined` Description: The color value **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. **`respectAlpha`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether to include the alpha channel in the color #### Data Attributes **`data-scope`**: color-picker **`data-part`**: swatch **`data-state`**: "checked" | "unchecked" **`data-value`**: The value of the item ### SwatchTrigger #### Props **`value`** Type: `string | Color` Required: true Default Value: `undefined` Description: The color value **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. **`disabled`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether the swatch trigger is disabled #### Data Attributes **`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 **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. **`size`** Type: `string` Required: false Default Value: `undefined` Description: undefined ### Trigger #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`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 **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. **`respectAlpha`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether to include the alpha channel in the color ### ValueText #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. **`format`** Type: `ColorStringFormat` Required: false Default Value: `undefined` Description: undefined #### Data Attributes **`data-scope`**: color-picker **`data-part`**: value-text **`data-disabled`**: Present when disabled **`data-focus`**: Present when focused ### View #### Props **`format`** Type: `ColorFormat` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ## 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 ```vueFramework Open Clear Frameworks {{ item }} ✓ Framework Open Clear {{ type }} {{ item.label }} ✓ Label Open Clear Frameworks {{ item }} ✓ Additional Info Error Info Framework Open Clear Frameworks {{ item }} ✓ Framework {{ item.label }} ✓ { navigate({ to: e.node.href }) }} > {/* ... */} ) } ``` ### 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. ```vueSearch Star Wars Characters Loading... {{ state.error.value.message }} {{ item.name }} - {{ item.height }}cm / {{ item.mass }}kg Framework Open Clear Frameworks {{ item }} Framework Open {{ item }} ✓ ; /* 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 ### Root #### Props **`allowCustomValue`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether to allow typing custom values in the input **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. **`autoFocus`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether to autofocus the input on mount **`closeOnSelect`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether to close the combobox when an item is selected. **`collection`** Type: `ListCollection ` Required: false Default Value: `undefined` Description: The collection of items **`composite`** Type: `boolean` Required: false Default Value: `true` Description: Whether the combobox is a composed with other composite widgets like tabs **`defaultHighlightedValue`** Type: `string` Required: false Default Value: `undefined` Description: The initial highlighted value of the combobox when rendered. Use when you don't need to control the highlighted value of the combobox. **`defaultInputValue`** Type: `string` Required: false Default Value: `""` Description: 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`** Type: `boolean` Required: false Default Value: `undefined` Description: The initial open state of the combobox when rendered. Use when you don't need to control the open state of the combobox. **`defaultValue`** Type: `string[]` Required: false Default Value: `[]` Description: 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`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether the combobox is disabled **`disableLayer`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether to disable registering this a dismissable layer **`form`** Type: `string` Required: false Default Value: `undefined` Description: The associate form of the combobox. **`highlightedValue`** Type: `string` Required: false Default Value: `undefined` Description: The controlled highlighted value of the combobox **`id`** Type: `string` Required: false Default Value: `undefined` Description: The unique identifier of the machine. **`ids`** Type: `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 }>` Required: false Default Value: `undefined` Description: The ids of the elements in the combobox. Useful for composition. **`inputBehavior`** Type: `'autocomplete' | 'none' | 'autohighlight'` Required: false Default Value: `"none"` Description: 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`** Type: `string` Required: false Default Value: `undefined` Description: The controlled value of the combobox's input **`invalid`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether the combobox is invalid **`lazyMount`** Type: `boolean` Required: false Default Value: `false` Description: Whether to enable lazy mounting **`loopFocus`** Type: `boolean` Required: false Default Value: `true` Description: Whether to loop the keyboard navigation through the items **`modelValue`** Type: `string[]` Required: false Default Value: `undefined` Description: The v-model value of the combobox **`multiple`** Type: `boolean` Required: false Default Value: `undefined` Description: 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`** Type: `string` Required: false Default Value: `undefined` Description: The `name` attribute of the combobox's input. Useful for form submission **`navigate`** Type: `(details: NavigateDetails) => void` Required: false Default Value: `undefined` Description: Function to navigate to the selected item **`open`** Type: `boolean` Required: false Default Value: `undefined` Description: The controlled open state of the combobox **`openOnChange`** Type: `boolean | ((details: InputValueChangeDetails) => boolean)` Required: false Default Value: `true` Description: Whether to show the combobox when the input value changes **`openOnClick`** Type: `boolean` Required: false Default Value: `false` Description: Whether to open the combobox popup on initial click on the input **`openOnKeyPress`** Type: `boolean` Required: false Default Value: `true` Description: Whether to open the combobox on arrow key press **`placeholder`** Type: `string` Required: false Default Value: `undefined` Description: The placeholder text of the combobox's input **`positioning`** Type: `PositioningOptions` Required: false Default Value: `{ placement: "bottom-start" }` Description: The positioning options to dynamically position the menu **`readOnly`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether the combobox is readonly. This puts the combobox in a "non-editable" mode but the user can still interact with it **`required`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether the combobox is required **`scrollToIndexFn`** Type: `(details: ScrollToIndexDetails) => void` Required: false Default Value: `undefined` Description: Function to scroll to a specific index **`selectionBehavior`** Type: `'replace' | 'clear' | 'preserve'` Required: false Default Value: `"replace"` Description: 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`** Type: `IntlTranslations` Required: false Default Value: `undefined` Description: Specifies the localized strings that identifies the accessibility elements and their states **`unmountOnExit`** Type: `boolean` Required: false Default Value: `false` Description: Whether to unmount on exit. #### Data Attributes **`data-scope`**: combobox **`data-part`**: root **`data-invalid`**: Present when invalid **`data-readonly`**: Present when read-only ### ClearTrigger #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: combobox **`data-part`**: clear-trigger **`data-invalid`**: Present when invalid ### Content #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: combobox **`data-part`**: content **`data-state`**: "open" | "closed" **`data-placement`**: The placement of the content **`data-empty`**: ### Control #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`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 ### Input #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: combobox **`data-part`**: input **`data-invalid`**: Present when invalid **`data-autofocus`**: **`data-state`**: "open" | "closed" ### ItemGroupLabel #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### ItemGroup #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. **`id`** Type: `string` Required: false Default Value: `undefined` Description: undefined #### Data Attributes **`data-scope`**: combobox **`data-part`**: item-group **`data-empty`**: ### ItemIndicator #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: combobox **`data-part`**: item-indicator **`data-state`**: "checked" | "unchecked" ### Item #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. **`item`** Type: `any` Required: false Default Value: `undefined` Description: The item to render **`persistFocus`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether hovering outside should clear the highlighted state #### Data Attributes **`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 **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: combobox **`data-part`**: item-text **`data-state`**: "checked" | "unchecked" **`data-disabled`**: Present when disabled **`data-highlighted`**: Present when highlighted ### Label #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: combobox **`data-part`**: label **`data-readonly`**: Present when read-only **`data-disabled`**: Present when disabled **`data-invalid`**: Present when invalid **`data-focus`**: Present when focused ### List #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: combobox **`data-part`**: list **`data-empty`**: ### Positioner #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### RootProvider #### Props **`value`** Type: `ComboboxApi Label 📅 Clear Prev Next {{ weekDay.short }} {{ day.day }} Prev Next {{ month.label }} Prev Next {{ year.label }} Label 📅 Clear Prev Next {{ weekDay.short }} {{ day.day }} Prev Next {{ month.label }} Prev Next {{ year.label }} Label 📅 Clear Last 7 days Prev Next {{ weekDay.short }} {{ day.day }} Prev Next {{ month.label }} Prev Next {{ year.label }} Label 📅 Clear Prev Next {{ weekDay.short }} {{ day.day }} {{ weekDay.short }} {{ day.day }} Prev Next {{ weekDay.short }} {{ day.day }} Prev Next {{ month.label }} Prev Next {{ year.label }} Label 📅 Clear Prev Next {{ weekDay.short }} {{ day.day }} Prev Next {{ month.label }} Prev Next {{ year.label }} ` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. **`lazyMount`** Type: `boolean` Required: false Default Value: `false` Description: Whether to enable lazy mounting **`unmountOnExit`** Type: `boolean` Required: false Default Value: `false` Description: Whether to unmount on exit. ### TableBody #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: date-picker **`data-part`**: table-body **`data-view`**: The view of the tablebody **`data-disabled`**: Present when disabled ### TableCell #### Props **`value`** Type: `Reactive ` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. **`columns`** Type: `number` Required: false Default Value: `undefined` Description: undefined **`disabled`** Type: `boolean` Required: false Default Value: `undefined` Description: undefined **`visibleRange`** Type: `VisibleRange` Required: false Default Value: `undefined` Description: undefined ### TableCellTrigger #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### TableHead #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: date-picker **`data-part`**: table-head **`data-view`**: The view of the tablehead **`data-disabled`**: Present when disabled ### TableHeader #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: date-picker **`data-part`**: table-header **`data-view`**: The view of the tableheader **`data-disabled`**: Present when disabled ### Table #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. **`columns`** Type: `number` Required: false Default Value: `undefined` Description: undefined **`id`** Type: `string` Required: false Default Value: `undefined` Description: undefined **`view`** Type: `DateView` Required: false Default Value: `undefined` Description: undefined #### Data Attributes **`data-scope`**: date-picker **`data-part`**: table **`data-columns`**: **`data-view`**: The view of the table ### TableRow #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: date-picker **`data-part`**: table-row **`data-disabled`**: Present when disabled **`data-view`**: The view of the tablerow ### Trigger #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: date-picker **`data-part`**: trigger **`data-placement`**: The placement of the trigger **`data-state`**: "open" | "closed" ### ViewControl #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: date-picker **`data-part`**: view-control **`data-view`**: The view of the viewcontrol ### View #### Props **`view`** Type: `DateView` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: date-picker **`data-part`**: view **`data-view`**: The view of the view ### ViewTrigger #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: date-picker **`data-part`**: view-trigger **`data-view`**: The view of the viewtrigger ### YearSelect #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ## 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 ```vue Open Dialog Dialog Title Dialog Description Close Dialog Title Dialog Description Close Open Dialog Dialog Title Dialog Description Close Open Dialog Loading...}> Open Dialog Dialog Title Dialog Description Close Dialog is {{ dialog.open ? 'open' : 'closed' }}
Open Dialog Dialog Title Dialog Description Close ` Required: true Default Value: `undefined` Description: undefined **`lazyMount`** Type: `boolean` Required: false Default Value: `false` Description: Whether to enable lazy mounting **`unmountOnExit`** Type: `boolean` Required: false Default Value: `false` Description: Whether to unmount on exit. ### Title #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### Trigger #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: dialog **`data-part`**: trigger **`data-state`**: "open" | "closed" ## 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: ```vue Label Label Save Cancel Edit {/*...*/} ``` ### Max width It is a common pattern to set a maximum of the editable as it auto-grows. To achieve this, set the `maxWidth` prop to the desired value. ```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{/*...*/} ``` ### Field The `Field` component helps manage form-related state and accessibility attributes of an editable. It includes handling ARIA labels, helper text, and error text to ensure proper accessibility. ```vueLabel Additional Info Error Info Label ` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### SubmitTrigger #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ## 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. ```vue 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 Additional Info Error Info Label Some additional Info Error Info 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 Checkbox ✔️ Field Heler Text Field Error Text Mobile Number {{ item }} File Upload Drop your files here Choose file(s) Generic IconX Choose file(s) X Label Select Additional Info Error Info File Upload Drop your files here Choose file(s) Generic IconX ` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### Trigger #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: file-upload **`data-part`**: trigger **`data-disabled`**: Present when disabled **`data-invalid`**: Present when invalid # Floating Panel ## 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 `FloatingPanel` component in your project. Let's take a look at the most basic example: ```vue Toggle Panel Floating Panel Some content
Toggle Panel Floating Panel Some content
Toggle Panel Floating Panel Some content
Toggle Panel Floating Panel Some content
Toggle Panel Floating Panel Some content
Toggle Panel Floating Panel Some content
floatingPanel is {{ floatingPanel.open ? 'open' : 'closed' }}
Toggle Panel Floating Panel Some content
` Required: true Default Value: `undefined` Description: undefined **`lazyMount`** Type: `boolean` Required: false Default Value: `false` Description: Whether to enable lazy mounting **`unmountOnExit`** Type: `boolean` Required: false Default Value: `false` Description: Whether to unmount on exit. ### StageTrigger #### Props **`stage`** Type: `Stage` Required: true Default Value: `undefined` Description: The stage of the panel **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### Title #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### Trigger #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: floating-panel **`data-part`**: trigger **`data-state`**: "open" | "closed" **`data-dragging`**: Present when in the dragging state # 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: ```vue Hover me Hover me Hover me Hover me {{ hoverCard.open ? '▲' : '▼' }} Hover me ` Required: true Default Value: `undefined` Description: undefined **`lazyMount`** Type: `boolean` Required: false Default Value: `false` Description: Whether to enable lazy mounting **`unmountOnExit`** Type: `boolean` Required: false Default Value: `false` Description: Whether to unmount on exit. ### Trigger #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: hover-card **`data-part`**: trigger **`data-placement`**: The placement of the trigger **`data-state`**: "open" | "closed" # 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. ```vue Framework {{ item }} Framework {{ item }} Select your Framework {{ item.label }} Select your Framework {{ item }} Select your Frameworks {{ type }} {{ item.label }} ` Required: true Default Value: `undefined` Description: The collection of items **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. **`defaultHighlightedValue`** Type: `string` Required: false Default Value: `undefined` Description: The initial value of the highlighted item when opened. Use when you don't need to control the highlighted value of the listbox. **`defaultValue`** Type: `string[]` Required: false Default Value: `[]` Description: The initial default value of the listbox when rendered. Use when you don't need to control the value of the listbox. **`deselectable`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether to disallow empty selection **`disabled`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether the listbox is disabled **`disallowSelectAll`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether to disallow selecting all items when `meta+a` is pressed **`highlightedValue`** Type: `string` Required: false Default Value: `undefined` Description: The controlled key of the highlighted item **`id`** Type: `string` Required: false Default Value: `undefined` Description: The unique identifier of the machine. **`ids`** Type: `Partial<{ root: string content: string label: string item(id: string | number): string itemGroup(id: string | number): string itemGroupLabel(id: string | number): string }>` Required: false Default Value: `undefined` Description: The ids of the elements in the listbox. Useful for composition. **`loopFocus`** Type: `boolean` Required: false Default Value: `false` Description: Whether to loop the keyboard navigation through the options **`modelValue`** Type: `string[]` Required: false Default Value: `undefined` Description: The model value of the listbox **`orientation`** Type: `'horizontal' | 'vertical'` Required: false Default Value: `"horizontal"` Description: The orientation of the element. **`scrollToIndexFn`** Type: `(details: ScrollToIndexDetails) => void` Required: false Default Value: `undefined` Description: Function to scroll to a specific index **`selectionMode`** Type: `SelectionMode` Required: false Default Value: `"single"` Description: 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`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether to select the item when it is highlighted **`typeahead`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether to enable typeahead on the listbox #### Data Attributes **`data-scope`**: listbox **`data-part`**: root **`data-orientation`**: The orientation of the listbox **`data-disabled`**: Present when disabled ### Content #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: listbox **`data-part`**: content **`data-activedescendant`**: **`data-orientation`**: The orientation of the content **`data-layout`**: **`data-empty`**: ### Input #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: listbox **`data-part`**: input **`data-disabled`**: Present when disabled ### ItemGroupLabel #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### ItemGroup #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. **`id`** Type: `string` Required: false Default Value: `undefined` Description: undefined #### Data Attributes **`data-scope`**: listbox **`data-part`**: item-group **`data-disabled`**: Present when disabled **`data-orientation`**: The orientation of the item **`data-empty`**: ### ItemIndicator #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: listbox **`data-part`**: item-indicator **`data-state`**: "checked" | "unchecked" ### Item #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. **`highlightOnHover`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether to highlight the item on hover **`item`** Type: `any` Required: false Default Value: `undefined` Description: The item to render #### Data Attributes **`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 **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: listbox **`data-part`**: item-text **`data-state`**: "checked" | "unchecked" **`data-disabled`**: Present when disabled **`data-highlighted`**: Present when highlighted ### Label #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: listbox **`data-part`**: label **`data-disabled`**: Present when disabled ### RootProvider #### Props **`value`** Type: `ListboxApi Open menu ➡️ React Solid Vue Open menu React Solid Vue Open menu JS Frameworks React Solid Vue CSS Frameworks Panda Tailwind Open menu React Solid Vue Right click me React Solid Vue Open menu JS Frameworks React Solid Vue CSS Frameworks Panda Tailwind Open menu ✅ Check me Open menu JS Frameworks ✅ {{ item }} Open menu ➡️ React Solid Vue 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 ` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### Scrubber #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: number-input **`data-part`**: scrubber **`data-disabled`**: Present when disabled ### ValueText #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: number-input **`data-part`**: value-text **`data-disabled`**: Present when disabled **`data-invalid`**: Present when invalid **`data-focus`**: Present when focused ## 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: ```vue Previous Page {{ page.value }} … Next Page Previous Page {{ page.value }} … Next Page Previous Page {{ page.value }} … Next Page ` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. # 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: ```vue Password Password Password Password Your password must be at least 8 characters Password is required API Key Password is {{ visible ? 'visible' : 'hidden' }} ` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### VisibilityTrigger #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: password-input **`data-part`**: visibility-trigger **`data-readonly`**: Present when read-only **`data-disabled`**: Present when disabled **`data-state`**: "visible" | "hidden" # 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: ```vue Label Label Label Label Label Label Label Additional Info Error Info Label ` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ## 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: ```vue Click Me {{ '>' }} Title Description Click Me {{ '>' }} Title Description Click Me Title Description Close Click Me {{ '>' }} Title Description Anchor Title Description Close Click Me Title Description Close Click Me Title Description Close Click Me Title Description Close Click Me {{ '>' }} 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 ### Root #### Props **`autoFocus`** Type: `boolean` Required: false Default Value: `true` Description: Whether to automatically set focus on the first focusable content within the popover when opened. **`closeOnEscape`** Type: `boolean` Required: false Default Value: `true` Description: Whether to close the popover when the escape key is pressed. **`closeOnInteractOutside`** Type: `boolean` Required: false Default Value: `true` Description: Whether to close the popover when the user clicks outside of the popover. **`defaultOpen`** Type: `boolean` Required: false Default Value: `undefined` Description: The initial open state of the popover when rendered. Use when you don't need to control the open state of the popover. **`id`** Type: `string` Required: false Default Value: `undefined` Description: The unique identifier of the machine. **`ids`** Type: `Partial<{ anchor: string trigger: string content: string title: string description: string closeTrigger: string positioner: string arrow: string }>` Required: false Default Value: `undefined` Description: The ids of the elements in the popover. Useful for composition. **`initialFocusEl`** Type: `() => HTMLElement | null` Required: false Default Value: `undefined` Description: The element to focus on when the popover is opened. **`lazyMount`** Type: `boolean` Required: false Default Value: `false` Description: Whether to enable lazy mounting **`modal`** Type: `boolean` Required: false Default Value: `false` Description: 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`** Type: `boolean` Required: false Default Value: `undefined` Description: The controlled open state of the popover **`persistentElements`** Type: `(() => Element | null)[]` Required: false Default Value: `undefined` Description: Returns the persistent elements that: - should not have pointer-events disabled - should not trigger the dismiss event **`portalled`** Type: `boolean` Required: false Default Value: `true` Description: Whether the popover is portalled. This will proxy the tabbing behavior regardless of the DOM position of the popover content. **`positioning`** Type: `PositioningOptions` Required: false Default Value: `undefined` Description: The user provided options used to position the popover content **`unmountOnExit`** Type: `boolean` Required: false Default Value: `false` Description: Whether to unmount on exit. #### Emits **`escapeKeyDown`** Type: `[event: KeyboardEvent]` Description: Function called when the escape key is pressed **`focusOutside`** Type: `[event: FocusOutsideEvent]` Description: Function called when the focus is moved outside the component **`interactOutside`** Type: `[event: InteractOutsideEvent]` Description: Function called when an interaction happens outside the component **`openChange`** Type: `[details: OpenChangeDetails]` Description: Function invoked when the popover opens or closes **`pointerDownOutside`** Type: `[event: PointerDownOutsideEvent]` Description: Function called when the pointer is pressed down outside the component **`update:open`** Type: `[open: boolean]` Description: The callback fired when the open state changes. ### Anchor #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### Arrow #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### ArrowTip #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### CloseTrigger #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### Content #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: popover **`data-part`**: content **`data-state`**: "open" | "closed" **`data-expanded`**: Present when expanded **`data-placement`**: The placement of the content ### Description #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### Indicator #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: popover **`data-part`**: indicator **`data-state`**: "open" | "closed" ### Positioner #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### RootProvider #### Props **`value`** Type: `PopoverApi ` Required: true Default Value: `undefined` Description: undefined **`lazyMount`** Type: `boolean` Required: false Default Value: `false` Description: Whether to enable lazy mounting **`unmountOnExit`** Type: `boolean` Required: false Default Value: `false` Description: Whether to unmount on exit. ### Title #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### Trigger #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: popover **`data-part`**: trigger **`data-placement`**: The placement of the trigger **`data-state`**: "open" | "closed" ## 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: ```vueLabel Label Label Label Label ` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### Track #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### ValueText #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### View #### Props **`state`** Type: `ProgressState` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`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: ```vue Label Label Label Label Label ` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### Track #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### ValueText #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### View #### Props **`state`** Type: `ProgressState` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`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: ```vue Download Download ``` ### With Overlay You can also add a logo or overlay to the QR code. This is useful when you want to brand the QR code. ```vue
` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. # 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. ### Design impact on the asChild property The `RadioGroup.Item` element of the radio group is a `label` element. This is because the radio group 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 > `RadioGroup.Item` component. ## Examples Learn how to use the `RadioGroup` component in your project. Let's take a look at the most basic example: ```vue Framework {{ framework }} Framework {{ framework }} Framework {{ framework }} Framework {{ framework }} Framework {{ framework }} ` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ## 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: ```vue Label Label Label Label {{ value }} Label Label Label Label Additional Info Error Info Label ` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ## 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. # 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: ```vue {{ framework }} {{ framework }} {{ framework }} {{ 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: ```vue Framework Clear Frameworks {{ item }} ✓ Framework Clear Frameworks {{ item.label }} ✓ Framework Clear {{ type }} {{ item.label }} ✓ Framework Clear Frameworks {{ item.label }} ✓ Label Clear Frameworks {{ item }} ✓ Additional Info Error Info Framework Clear Loading...Error: {{ error.message }}{{ item }} ✓ Framework Clear Frameworks {{ item }} ✓ Framework Clear Frameworks {{ item }} ✓ Framework Clear Frameworks {{ item.label }} ✓ ; /* 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='select'][data-part='content'] { max-height: calc(var(--available-height) - 100px); } ``` ## API Reference ### Root #### Props **`collection`** Type: `ListCollection ` Required: true Default Value: `undefined` Description: The collection of items **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. **`closeOnSelect`** Type: `boolean` Required: false Default Value: `true` Description: Whether the select should close after an item is selected **`composite`** Type: `boolean` Required: false Default Value: `true` Description: Whether the select is a composed with other composite widgets like tabs or combobox **`defaultHighlightedValue`** Type: `string` Required: false Default Value: `undefined` Description: The initial value of the highlighted item when opened. Use when you don't need to control the highlighted value of the select. **`defaultOpen`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether the select's open state is controlled by the user **`defaultValue`** Type: `string[]` Required: false Default Value: `undefined` Description: The initial default value of the select when rendered. Use when you don't need to control the value of the select. **`deselectable`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether the value can be cleared by clicking the selected item. **Note:** this is only applicable for single selection **`disabled`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether the select is disabled **`form`** Type: `string` Required: false Default Value: `undefined` Description: The associate form of the underlying select. **`highlightedValue`** Type: `string` Required: false Default Value: `undefined` Description: The controlled key of the highlighted item **`id`** Type: `string` Required: false Default Value: `undefined` Description: The unique identifier of the machine. **`ids`** Type: `Partial<{ root: string content: string control: string trigger: string clearTrigger: string label: string hiddenSelect: string positioner: string item(id: string | number): string itemGroup(id: string | number): string itemGroupLabel(id: string | number): string }>` Required: false Default Value: `undefined` Description: The ids of the elements in the select. Useful for composition. **`invalid`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether the select is invalid **`lazyMount`** Type: `boolean` Required: false Default Value: `false` Description: Whether to enable lazy mounting **`loopFocus`** Type: `boolean` Required: false Default Value: `false` Description: Whether to loop the keyboard navigation through the options **`modelValue`** Type: `string[]` Required: false Default Value: `undefined` Description: The model value of the select **`multiple`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether to allow multiple selection **`name`** Type: `string` Required: false Default Value: `undefined` Description: The `name` attribute of the underlying select. **`open`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether the select menu is open **`positioning`** Type: `PositioningOptions` Required: false Default Value: `undefined` Description: The positioning options of the menu. **`readOnly`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether the select is read-only **`required`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether the select is required **`scrollToIndexFn`** Type: `(details: ScrollToIndexDetails) => void` Required: false Default Value: `undefined` Description: Function to scroll to a specific index **`unmountOnExit`** Type: `boolean` Required: false Default Value: `false` Description: Whether to unmount on exit. #### Data Attributes **`data-scope`**: select **`data-part`**: root **`data-invalid`**: Present when invalid **`data-readonly`**: Present when read-only ### ClearTrigger #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: select **`data-part`**: clear-trigger **`data-invalid`**: Present when invalid ### Content #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: select **`data-part`**: content **`data-state`**: "open" | "closed" **`data-placement`**: The placement of the content **`data-activedescendant`**: ### Control #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: select **`data-part`**: control **`data-state`**: "open" | "closed" **`data-focus`**: Present when focused **`data-disabled`**: Present when disabled **`data-invalid`**: Present when invalid ### HiddenSelect #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### Indicator #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: select **`data-part`**: indicator **`data-state`**: "open" | "closed" **`data-disabled`**: Present when disabled **`data-invalid`**: Present when invalid **`data-readonly`**: Present when read-only ### ItemGroupLabel #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### ItemGroup #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. **`id`** Type: `string` Required: false Default Value: `undefined` Description: undefined #### Data Attributes **`data-scope`**: select **`data-part`**: item-group **`data-disabled`**: Present when disabled ### ItemIndicator #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: select **`data-part`**: item-indicator **`data-state`**: "checked" | "unchecked" ### Item #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. **`item`** Type: `any` Required: false Default Value: `undefined` Description: The item to render **`persistFocus`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether hovering outside should clear the highlighted state #### Data Attributes **`data-scope`**: select **`data-part`**: item **`data-value`**: The value of the item **`data-state`**: "checked" | "unchecked" **`data-highlighted`**: Present when highlighted **`data-disabled`**: Present when disabled ### ItemText #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: select **`data-part`**: item-text **`data-state`**: "checked" | "unchecked" **`data-disabled`**: Present when disabled **`data-highlighted`**: Present when highlighted ### Label #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: select **`data-part`**: label **`data-disabled`**: Present when disabled **`data-invalid`**: Present when invalid **`data-readonly`**: Present when read-only ### List #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### Positioner #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### RootProvider #### Props **`value`** Type: `SelectApi
When focus is on the content, selects the highlighted item. **`Enter`** Description: When focus is on trigger, opens the select and focuses the first selected item.
When focus is on content, selects the focused item. **`ArrowDown`** Description: When focus is on trigger, opens the select.
When focus is on content, moves focus to the next item. **`ArrowUp`** Description: When focus is on trigger, opens the select.
When focus is on content, moves focus to the previous item. **`Esc`** Description: Closes the select and moves focus to trigger. **`A-Z + a-z`** Description: When focus is on trigger, selects the item whose label starts with the typed character.
When focus is on the listbox, moves focus to the next item with a label that starts with the typed character. # Signature Pad ## Anatomy To set up the signature pad 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 `Signature Pad` component in your project. Let's take a look at the most basic example: ```vueSign below Clear Sign below Clear ``` ### Using the Field Component The `Field` component helps manage form-related state and accessibility attributes of a signature pad. It includes handling ARIA labels, helper text, and error text to ensure proper accessibility. ```vue
Label Clear Additional Info Error Info Sign below Clear ` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### Segment #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. # Slider ## Anatomy To set up the slider 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 `Slider` component in your project. Let's take a look at the most basic example: ```vue Label Label Label 0 * 50 * Label * * * Label Label Label Label Label Label ` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### Thumb #### Props **`index`** Type: `number` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. **`name`** Type: `string` Required: false Default Value: `undefined` Description: undefined #### Data Attributes **`data-scope`**: slider **`data-part`**: thumb **`data-index`**: The index of the item **`data-name`**: **`data-disabled`**: Present when disabled **`data-orientation`**: The orientation of the thumb **`data-focus`**: Present when focused **`data-dragging`**: Present when in the dragging state ### Track #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: slider **`data-part`**: track **`data-disabled`**: Present when disabled **`data-invalid`**: Present when invalid **`data-dragging`**: Present when in the dragging state **`data-orientation`**: The orientation of the track **`data-focus`**: Present when focused ### ValueText #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: slider **`data-part`**: value-text **`data-disabled`**: Present when disabled **`data-orientation`**: The orientation of the valuetext **`data-invalid`**: Present when invalid **`data-focus`**: Present when focused ## Accessibility Complies with the [Slider WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider/). ### Keyboard Support **`ArrowRight`** Description: Increments the slider based on defined step **`ArrowLeft`** Description: Decrements the slider based on defined step **`ArrowUp`** Description: Increases the value by the step amount. **`ArrowDown`** Description: Decreases the value by the step amount. **`PageUp`** Description: Increases the value by a larger step **`PageDown`** Description: Decreases the value by a larger step **`Shift + ArrowUp`** Description: Increases the value by a larger step **`Shift + ArrowDown`** Description: Decreases the value by a larger step **`Home`** Description: Sets the value to its minimum. **`End`** Description: Sets the value to its maximum. # Splitter ## Anatomy To set up the splitter 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 `Splitter` component in your project. Let's take a look at the most basic example: ```vue A B A B A B A B A B C A B ` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ## Accessibility Complies with the [Window Splitter WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/). # Steps ## Usage The `Steps` component is used to guide users through a series of steps in a process. - Supports horizontal and vertical orientations. - Support for changing the active step with the keyboard and pointer. - Support for linear and non-linear steps. ```jsx import { Steps } from '@ark-ui/react/steps' ``` ## Examples ### Basic Here's a basic example of the `Steps` component. ```vue {{ index + 1 }} {{ item.title }}{{ item.title }} - {{ item.description }} Steps Complete - Thank you for filling out the form! Back Next {{ index + 1 }} {{ item.title }}{{ item.title }} - {{ item.description }} Steps Complete - Thank you for filling out the form! Back Next ` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### Separator #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: steps **`data-part`**: separator **`data-orientation`**: The orientation of the separator **`data-complete`**: Present when the separator value is complete **`data-current`**: Present when current **`data-incomplete`**: ### Trigger #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: steps **`data-part`**: trigger **`data-state`**: "open" | "closed" **`data-orientation`**: The orientation of the trigger **`data-complete`**: Present when the trigger value is complete **`data-current`**: Present when current **`data-incomplete`**: # Switch ## Anatomy To set up the switch 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 `Switch.Root` element of the switch is a `label` element. This is because the switch 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 `Switch.Root` > component. ## Examples Learn how to use the `Switch` component in your project. Let's take a look at the most basic example: ```vue Label Label Feature is {{ api.checked ? 'enabled' : 'disabled' }} Label Additional Info Error Info Label ` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### Thumb #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`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`**: "checked" | "unchecked" **`data-invalid`**: Present when invalid ## Accessibility Complies with the [Switch WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/). ### Keyboard Support **`Space + Enter`** Description: Toggle the switch # Tabs ## Anatomy To set up the tabs 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 `Tabs` component in your project. Let's take a look at the most basic example: ```vue React Vue Solid React Content Vue Content Solid Content React Vue Solid React Content Vue Content Solid Content React Vue Solid React Content Vue Content Solid Content React Vue Solid React Content Vue Content Solid Content React Vue Solid React Content Vue Content Solid Content Selected tab: {{ value }}
React Vue Solid React Content Vue Content Solid Content { navigate(`/${value === 'home' ? '' : value}`) }} > ) } ``` ### Vertical Tabs The default orientation of the tabs is `horizontal`. To change the orientation, set the `orientation` prop to `vertical`. ```vueHome Page 1 Page 2 React Vue Solid React Content Vue Content Solid Content React Vue Solid React Content Vue Content Solid Content React Vue Solid React Content Vue Content Solid Content ` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. **`lazyMount`** Type: `boolean` Required: false Default Value: `false` Description: Whether to enable lazy mounting **`unmountOnExit`** Type: `boolean` Required: false Default Value: `false` Description: Whether to unmount on exit. ## Accessibility Complies with the [Tabs WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/). ### Keyboard Support **`Tab`** Description: When focus moves onto the tabs, focuses the active trigger. When a trigger is focused, moves focus to the active content. **`ArrowDown`** Description: Moves focus to the next trigger in vertical orientation and activates its associated content. **`ArrowRight`** Description: Moves focus to the next trigger in horizontal orientation and activates its associated content. **`ArrowUp`** Description: Moves focus to the previous trigger in vertical orientation and activates its associated content. **`ArrowLeft`** Description: Moves focus to the previous trigger in horizontal orientation and activates its associated content. **`Home`** Description: Moves focus to the first trigger and activates its associated content. **`End`** Description: Moves focus to the last trigger and activates its associated content. **`Enter + Space`** Description: In manual mode, when a trigger is focused, moves focus to its associated content. # Tags Input ## Anatomy To set up the tags 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 `TagsInput` component in your project. Let's take a look at the most basic example: ```vue Frameworks {{ value }} Delete Clear all Frameworks {{ value }} Delete Clear all Frameworks {{ value }} Delete Clear all Frameworks {{ value }} Delete Clear all Frameworks {{ value }} Delete Clear all Frameworks {{ value }} Delete Clear all Frameworks {{ value }} Delete Clear all Frameworks {{ value }} Delete Clear all Label {{ value }} Delete Clear all Additional Info Error Info Frameworks {{ value }} Delete Clear all ` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ## Accessibility ### Keyboard Support **`ArrowLeft`** Description: Moves focus to the previous tag item **`ArrowRight`** Description: Moves focus to the next tag item **`Backspace`** Description: Deletes the tag item that has visual focus or the last tag item **`Enter`** Description: When a tag item has visual focus, it puts the tag in edit mode.
When the input has focus, it adds the value to the list of tags **`Delete`** Description: Deletes the tag item that has visual focus **`Control + V`** Description: When `addOnPaste` is set. Adds the pasted value as a tags # Timer ## Examples Learn how to use the `Timer` component in your project. Let's take a look at the most basic example: ```vue: : : Play Resume Pause : : : : : : Play Resume Pause ` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: timer **`data-part`**: item **`data-type`**: The type of the item ### RootProvider #### Props **`value`** Type: `TimerApi ` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### Separator #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. # Toast ## Anatomy To set up the toast 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. ## Setup To use the Toast component, create the toast engine using the `createToaster` function. This function manages the placement and grouping of toasts, and provides a `toast` object needed to create toast notification. ```ts const toaster = createToaster({ placement: 'bottom-end', overlap: true, gap: 24, }) ``` ## Examples Here's an example of creating a toast using the `toast.create` method. ```vue {{ toast.title }} {{ toast.description }} Action Close ``` ### Action To add an action to a toast, use the `toast.action` property. ```vue{{ toast.title }} {{ toast.description }} ``` ## API Reference ### Root #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: toast **`data-part`**: root **`data-state`**: "open" | "closed" **`data-type`**: The type of the item **`data-placement`**: The placement of the toast **`data-align`**: **`data-side`**: **`data-mounted`**: Present when mounted **`data-paused`**: Present when paused **`data-first`**: **`data-sibling`**: **`data-stack`**: **`data-overlap`**: Present when overlapping ### ActionTrigger #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### CloseTrigger #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### Description #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### Title #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### Toaster #### Props **`toaster`** Type: `CreateToasterReturn` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. # Toggle Group ## Anatomy To set up the toggle 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 `ToggleGroup` component in your project. Let's take a look at the most basic example: ```vue{{ toast.title }} {{ toast.description }} {{ toast.action?.label }} A B C A B C A B C A B C ` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ## Accessibility ### Keyboard Support **`Tab`** Description: Moves focus to either the pressed item or the first item in the group. **`Space`** Description: Activates/deactivates the item. **`Enter`** Description: Activates/deactivates the item. **`ArrowDown`** Description: Moves focus to the next item in the group. **`ArrowRight`** Description: Moves focus to the next item in the group. **`ArrowUp`** Description: Moves focus to the previous item in the group. **`ArrowLeft`** Description: Moves focus to the previous item in the group. **`Home`** Description: Moves focus to the first item. **`End`** Description: Moves focus to the last item. # Toggle ## Examples Here's a basic example of how to use the `Toggle` component: ```vue Volume is {{ pressed ? 'unmuted' : 'muted' }}
Hover Me I am a tooltip! Hover Me I am a tooltip! Hover Me This tooltip is open: {{ tooltip.open.toString() }} Hover Me Hover Me I am a tooltip! Hover Me I am a tooltip! Hover Me I am a tooltip! ` Required: true Default Value: `undefined` Description: undefined **`lazyMount`** Type: `boolean` Required: false Default Value: `false` Description: Whether to enable lazy mounting **`unmountOnExit`** Type: `boolean` Required: false Default Value: `false` Description: Whether to unmount on exit. ### Trigger #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: tooltip **`data-part`**: trigger **`data-expanded`**: Present when expanded **`data-state`**: "open" | "closed" ## Accessibility Complies with the [Tooltip WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/). ### Keyboard Support **`Tab`** Description: Opens/closes the tooltip without delay. **`Escape`** Description: If open, closes the tooltip without delay. # Tour ## Features - Support for different step types such as "dialog", "floating", "tooltip" or "wait" - Support for customizable content per step - Wait steps for waiting for a specific selector to appear on the page before showing the next step - Flexible positioning of the tour dialog per step - Progress tracking shows users their progress through the tour ## Anatomy To set up the tour 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. ## Steps ### Using step types The tour machine supports different types of steps, allowing you to create a diverse and interactive tour experience. The available step types are defined in the `StepType` type: - `tooltip`: Displays the step content as a tooltip, typically positioned near the target element. - `dialog`: Shows the step content in a modal dialog centered on screen, useful for starting or ending the tour. This usually don't have a `target` defined. - `floating`: Presents the step content as a floating element, which can be positioned flexibly on the screen. This usually don't have a `target` defined. - `wait`: A special type that waits for a specific condition before proceeding to the next step. ```tsx const steps: TourStepDetails[] = [ { id: 'step-1', type: 'tooltip', placement: 'top-start', target: () => document.querySelector('#target-1'), title: 'Tooltip Step', description: 'This is a tooltip step', }, { id: 'step-2', type: 'dialog', title: 'Dialog Step', description: 'This is a dialog step', }, { id: 'step-3', type: 'floating', placement: 'top-start', title: 'Floating Step', description: 'This is a floating step', }, { id: 'step-4', type: 'wait', title: 'Wait Step', description: 'This is a wait step', effect({ next }) { // do something and go next // you can also return a cleanup }, }, ] ``` ### Configuring actions Every step supports a list of actions that are rendered in the step footer.Use the `actions` property to define each action. ```tsx const steps: TourStepDetails[] = [ { id: 'step-1', type: 'dialog', title: 'Dialog Step', description: 'This is a dialog step', actions: [{ label: 'Show me a tour!', action: 'next' }], }, ] ``` ### Changing tooltip placement Use the `placement` property to define the placement of the tooltip. ```tsx {5} const steps: TourStepDetails[] = [ { id: 'step-1', type: 'tooltip', placement: 'top-start', // ... }, ] ``` ### Hiding the arrow Set `arrow: false` in the step property to hide the tooltip arrow. This is only useful for tooltip steps. ```tsx {5} const steps: TourStepDetails[] = [ { id: 'step-1', type: 'tooltip', arrow: false, }, ] ``` ### Hiding the backdrop Set `backdrop: false` in the step property to hide the backdrop. This applies to all step types except the `wait` step. ```tsx {5} const steps: TourStepDetails[] = [ { id: 'step-1', type: 'dialog', backdrop: false, }, ] ``` ### Step Effects Step effects are functions that are called before a step is opened. They are useful for adding custom logic to a step. This function provides the following methods: - `next()`: Call this method to move to the next step. - `show()`: Call this method to show the current step. - `update(details: StepDetails)`: Call this method to update the details of the current step (say, after data has been fetched). ```tsx const steps: TourStepDetails[] = [ { id: 'step-1', type: 'tooltip', effect({ next, show, update }) { fetchData().then((res) => { // update the step details update({ title: res.title }) // then show show the step show() }) return () => { // cleanup fetch data } }, }, ] ``` ### Wait Steps Wait steps are useful when you need to wait for a specific condition before proceeding to the next step. Use the step `effect` function to perform an action and then call `next()` to move to the next step. > **Note:** You cannot call `show()` in a wait step. ```tsx const steps: TourStepDetails[] = [ { id: 'step-1', type: 'wait', effect({ next }) { const button = document.querySelector('#button') const listener = () => next() button.addEventListener('click', listener) return () => button.removeEventListener('click', listener) }, }, ] ``` ## Styling guide Ensure the `box-sizing` is set to `border-box` for the means of measuring the tour target. ```css * { box-sizing: border-box; } ``` Ensure the `body` has a `position` of `relative`. ```css body { position: relative; } ``` ## API Reference ### Root #### Props **`tour`** Type: `TourApi ` Required: true Default Value: `undefined` Description: undefined **`lazyMount`** Type: `boolean` Required: false Default Value: `false` Description: Whether to enable lazy mounting **`unmountOnExit`** Type: `boolean` Required: false Default Value: `false` Description: Whether to unmount on exit. #### Emits **`focusOutside`** Type: `[event: FocusOutsideEvent]` Description: Function called when the focus is moved outside the component **`interactOutside`** Type: `[event: InteractOutsideEvent]` Description: Function called when an interaction happens outside the component **`pointerDownOutside`** Type: `[event: PointerDownOutsideEvent]` Description: Function called when the pointer is pressed down outside the component **`statusChange`** Type: `[details: StatusChangeDetails]` Description: Callback when the tour is opened or closed **`stepChange`** Type: `[details: StepChangeDetails]` Description: Callback when the highlighted step changes **`stepsChange`** Type: `[details: { steps: StepDetails[] }]` Description: Callback when the steps change ### ActionTrigger #### Props **`action`** Type: `StepAction` Required: true Default Value: `undefined` Description: undefined **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: tour **`data-part`**: action-trigger **`data-type`**: The type of the item **`data-disabled`**: Present when disabled ### Arrow #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### ArrowTip #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### Backdrop #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: tour **`data-part`**: backdrop **`data-state`**: "open" | "closed" **`data-type`**: The type of the item ### CloseTrigger #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: tour **`data-part`**: close-trigger **`data-type`**: The type of the item ### Content #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: tour **`data-part`**: content **`data-state`**: "open" | "closed" **`data-type`**: The type of the item **`data-placement`**: The placement of the content **`data-step`**: ### Control #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### Description #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: tour **`data-part`**: description **`data-placement`**: The placement of the description ### Positioner #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: tour **`data-part`**: positioner **`data-type`**: The type of the item **`data-placement`**: The placement of the positioner ### ProgressText #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### Spotlight #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### Title #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: tour **`data-part`**: title **`data-placement`**: The placement of the title # Tree View ## Anatomy To set up the tree view 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 `TreeView` component in your project. Let's take a look at the most basic example: ```vue Tree Tree Tree Tree Tree Tree ``` ### Links Tree items can be rendered as links to another page or website. This could be useful for documentation sites. Here's an example that modifies the tree collection to represent an hierarchical link structure. It uses the `asChild` prop to render the tree items as links, passing the `href` prop to a `` element. ```vueDocs ` Required: true Default Value: `undefined` Description: The collection of tree nodes **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. **`defaultExpandedValue`** Type: `string[]` Required: false Default Value: `undefined` Description: The initial expanded node ids when rendered. Use when you don't need to control the expanded node ids. **`defaultSelectedValue`** Type: `string[]` Required: false Default Value: `undefined` Description: The initial selected node ids when rendered. Use when you don't need to control the selected node ids. **`expandedValue`** Type: `string[]` Required: false Default Value: `undefined` Description: The controlled expanded node ids **`expandOnClick`** Type: `boolean` Required: false Default Value: `true` Description: Whether clicking on a branch should open it or not **`focusedValue`** Type: `string` Required: false Default Value: `undefined` Description: The id of the focused node **`id`** Type: `string` Required: false Default Value: `undefined` Description: The unique identifier of the machine. **`ids`** Type: `Partial<{ root: string; tree: string; label: string; node(value: string): string }>` Required: false Default Value: `undefined` Description: The ids of the tree elements. Useful for composition. **`lazyMount`** Type: `boolean` Required: false Default Value: `false` Description: Whether to enable lazy mounting **`selectedValue`** Type: `string[]` Required: false Default Value: `undefined` Description: The controlled selected node ids **`selectionMode`** Type: `'multiple' | 'single'` Required: false Default Value: `"single"` Description: Whether the tree supports multiple selection - "single": only one node can be selected - "multiple": multiple nodes can be selected **`typeahead`** Type: `boolean` Required: false Default Value: `true` Description: Whether the tree supports typeahead search **`unmountOnExit`** Type: `boolean` Required: false Default Value: `false` Description: Whether to unmount on exit. ### BranchContent #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: tree-view **`data-part`**: branch-content **`data-state`**: "open" | "closed" **`data-depth`**: The depth of the item **`data-path`**: The path of the item **`data-value`**: The value of the item ### BranchControl #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: tree-view **`data-part`**: branch-control **`data-path`**: The path of the item **`data-state`**: "open" | "closed" **`data-disabled`**: Present when disabled **`data-selected`**: Present when selected **`data-focus`**: Present when focused **`data-value`**: The value of the item **`data-depth`**: The depth of the item **`data-loading`**: ### BranchIndentGuide #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: tree-view **`data-part`**: branch-indent-guide **`data-depth`**: The depth of the item ### BranchIndicator #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: tree-view **`data-part`**: branch-indicator **`data-state`**: "open" | "closed" **`data-disabled`**: Present when disabled **`data-selected`**: Present when selected **`data-focus`**: Present when focused **`data-loading`**: ### Branch #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: tree-view **`data-part`**: branch **`data-depth`**: The depth of the item **`data-branch`**: **`data-value`**: The value of the item **`data-path`**: The path of the item **`data-selected`**: Present when selected **`data-state`**: "open" | "closed" **`data-disabled`**: Present when disabled **`data-loading`**: ### BranchText #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: tree-view **`data-part`**: branch-text **`data-disabled`**: Present when disabled **`data-state`**: "open" | "closed" **`data-loading`**: ### BranchTrigger #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: tree-view **`data-part`**: branch-trigger **`data-disabled`**: Present when disabled **`data-state`**: "open" | "closed" **`data-value`**: The value of the item **`data-loading`**: ### ItemIndicator #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: tree-view **`data-part`**: item-indicator **`data-disabled`**: Present when disabled **`data-selected`**: Present when selected **`data-focus`**: Present when focused ### Item #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: tree-view **`data-part`**: item **`data-path`**: The path of the item **`data-value`**: The value of the item **`data-focus`**: Present when focused **`data-selected`**: Present when selected **`data-disabled`**: Present when disabled **`data-depth`**: The depth of the item ### ItemText #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. #### Data Attributes **`data-scope`**: tree-view **`data-part`**: item-text **`data-disabled`**: Present when disabled **`data-selected`**: Present when selected **`data-focus`**: Present when focused ### Label #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### NodeProvider #### Props **`indexPath`** Type: `number[]` Required: true Default Value: `undefined` Description: The index path of the tree node **`node`** Type: `NonNullable ` Required: false Default Value: `undefined` Description: The tree node ### RootProvider #### Props **`value`** Type: `TreeViewApi
When focus is on an open branch node, moves focus to the first item node. **`ArrowLeft`** Description: When focus is on an open branch node, closes the node.
When focus is on an item or branch node, moves focus to its parent branch node. **`Home`** Description: Moves focus to first node without opening or closing a node. **`End`** Description: Moves focus to the last node that can be focused without expanding any nodes that are closed. **`a-z + A-Z`** Description: Focus moves to the next node with a name that starts with the typed character. The search logic ignores nodes that are descendants of closed branch. **`*`** Description: Expands all sibling nodes that are at the same depth as the focused node. **`Shift + ArrowDown`** Description: Moves focus to and toggles the selection state of the next node. **`Shift + ArrowUp`** Description: Moves focus to and toggles the selection state of the previous node. **`Ctrl + A`** Description: Selects all nodes in the tree. If all nodes are selected, unselects all nodes. # UTILITIES --- # Client Only ## Motivation The `ClientOnly` component renders its children only on the client side. This is useful for components that need to access the DOM or browser APIs that are not available on the server side. ## Examples ### Basic ```vue Example not found``` ### With Fallback ```vue Example not found``` ## API Reference # Download Trigger ## Motivation The `DownloadTrigger` component provides a convenient way to programmatically trigger file downloads in web applications. It handles the complexities of downloading files, whether they are URLs, Blobs, or other data types. ## Examples ### Basic Pass the data you want to download to the `data` prop, and specify the `fileName` and `mimeType` of the file. ```vueDownload txt ``` ### Download SVG Here's an example of how to download an SVG file. ```vueDownload SVG ``` ### Promise You can also trigger downloads from a promise that returns a `Blob`, `File`, or `string`. ```vueDownload Image ``` ## API Reference # Environment ## Motivation We use [Zag.js](https://zagjs.com/overview/composition#custom-window-environment) internally, which relies on DOM query methods like `document.querySelectorAll` and `document.getElementById`. In custom environments like iframes, Shadow DOM, or Electron, these methods might not work as expected. To handle this, Ark UI includes the `EnvironmentProvider`, allowing you to set the appropriate root node or document, ensuring correct DOM queries. ## Setup To support custom environments like an iframe, Shadow DOM or Electron, render the `EnvironmentProvider` component to provide the environment context to all Ark UI components. ```vue ``` ### Usage in iframe The `EnvironmentProvider` component will automatically detect the current environment and set the correct environment context. However, you can also manually set the `Document` like shown in this React example below: ```jsx import Frame, { FrameContextConsumer } from 'react-frame-component' import { EnvironmentProvider } from '@ark-ui/react' export const App = () => ({({ document }) => ) ``` ### Usage in Shadow DOM Here's an example of how to set the `EnvironmentProvider`'s value with Shadow DOM in Solid.js `Portal` component. ```jsx import { EnvironmentProvider } from '@ark-ui/react' import { Index, Portal } from 'solid-js/web' export const App = () => { let portalNode return ({/* Your App */} }portalNode?.shadowRoot ?? document}>{/* Your App */} {{ JSON.stringify(environment.getRootNode(), null, 2) }}``` ## API Reference ### EnvironmentProvider #### Props **`value`** Type: `RootNode | (() => RootNode)` Required: false Default Value: `undefined` Description: undefined # Focus Trap ## Motivation Focus trapping is essential for modal interfaces and other interactive elements that require user attention. The `FocusTrap` component helps maintain accessibility by ensuring keyboard focus remains within a designated container until explicitly released. ## Examples ```vue``` ### Percentage Use the `style="percent"` prop to format the number as a percentage. ```vue ``` ### Currency Use the `style="currency"` prop along with the `currency` prop to format the number as a currency. ```vue ``` ### Locale Use the `locale` prop to format the number according to a specific locale. ```vue ``` ### Compact Notation Use the `notation="compact"` prop to format the number in compact notation. ```vue ``` # Format Relative Time ## Usage The relative time formatting logic is handled by the native `Intl.RelativeTimeFormat` API and smartly cached to avoid performance issues when using the same locale and options. ```jsx import { Format } from '@ark-ui/react' ``` ## Examples ### Basic Use the `Format.RelativeTime` component to format a relative time with default options. ```vue Edited``` ### Short Use the `style="short"` prop to format the relative time in short format. ```vueEdited``` # Frame ## Usage The `Frame` component is used to render a component in an iframe. - Tracks the size of the content and exposes them via css variables. - Support for `head` prop to inject scripts and styles. - Support for mount and unmount callbacks. ```jsx import { Frame } from '@ark-ui/react' ``` ## Examples ### Basic Wrap your component in the `Frame` component to render it in an iframe. ```vueHello from inside the frame!
This content is rendered within our custom frame component using a Portal.
body { background-color: #f0f0f0; } ``` ### Injecting Script Using the `onMount` prop, you can inject a script into the iframe. ```vue``` ### Custom src doc Use the `srcDoc` prop to specify the HTML content of the page to use in the iframe. ```vueHello from inside the frame!
This content is rendered within our custom frame component using a Portal.
Hello from inside the frame!
This content is rendered within our custom frame component using a Portal.
``` # Highlight ## Usage The Highlight component takes a `text` prop containing the full text and a `query` prop specifying the text to highlight. It then renders the text with highlighted portions wrapped in `` tags. ```vue``` ### Multiple Queries You can highlight multiple terms by passing an array of strings to the `query` prop. ```vue ``` ### Case Sensitivity By default, the highlighting is case-sensitive. Use the `ignoreCase` prop to make it case-insensitive. ```vue ``` ### Match All By default, the Highlight component matches the first occurrence of the query. To highlight all occurrences of the query, set the `matchAll` prop to `true`. ```vue ``` ## API Reference ### Highlight #### Props **`query`** Type: `string | string[]` Required: true Default Value: `undefined` Description: The query to highlight in the text **`text`** Type: `string` Required: true Default Value: `undefined` Description: The text to highlight **`ignoreCase`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether to ignore case while matching **`matchAll`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether to match multiple instances of the query ## Customization The Highlight component wraps matched text in `` tags. ```tsxMatch All
Match First Occurrence Only
``` Style the `mark` tags using CSS to customize the appearance of highlighted text. ```css .highlighted-text { background-color: yellow; } ``` # Locale ## Setup The `LocaleProvider` component sets the locale for your app, formatting dates, numbers, and other locale-specific data. > **Note:** If no `LocaleProvider` is setup, the default locale for the app will be `en-US` and therefore the direction > will be `ltr`. ```vue ``` ## Usage To access the current locale and direction settings, use the `useLocaleContext` hook. ```vue {{ JSON.stringify(locale, null, 2) }}``` ## API Reference ### LocaleProvider #### Props **`locale`** Type: `string` Required: true Default Value: `'en-US'` Description: The locale to use for the application. # Presence ## Examples By default the child component starts out as hidden and remains hidden after the `present` state is toggled off. This is useful for situations where the element needs to be hidden initially and continue to stay hidden after its presence is no longer required. ```vue``` ### Lazy Mount To delay the mounting of a child component until the `present` prop is set to true, use the `lazyMount` prop: ```vueHidden and Hidden ``` ### Unmount on Exit To remove the child component from the DOM when it's not present, use the `unmountOnExit` prop: ```vueHidden and Hidden ``` ### Combining Lazy Mount and Unmount on Exit Both `lazyMount` and `unmountOnExit` can be combined for a component to be mounted only when it's present and to be unmounted when it's no longer present: ```vueHidden and Unmounted on Exit ``` ## API Reference ### Presence #### Props **`immediate`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether to synchronize the present change immediately or defer it to the next frame **`onExitComplete`** Type: `VoidFunction` Required: false Default Value: `undefined` Description: Function called when the animation ends in the closed state **`present`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether the node is present (controlled by the user) #### Emits **`exitComplete`** Type: `[]` Description: Function called when the animation ends in the closed stateLazy Mount and Unmounted on Exit
- `.
- **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]
### Fixed
- **Collection**: Export `UseListCollectionReturn` type
## [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
Item 1 Content 1 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]
### Fixed
- **Collection**: Export `UseListCollectionReturn` type
## [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
- **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.4] - 2025-06-27
### Fixed
- **Combobox, Select, Listbox**: Fix issue where rehydrating `defaultValue` or `value` after fetching items doesn't
update the `valueAsString`
## [5.15.3] - 2025-06-27
### Fixed
- **Tree View**: Fix tree traversal for querying last node
## [5.15.2] - 2025-06-26
### Fixed
- **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
- **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/solid/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/solid/password-input'
import { EyeIcon, EyeOffIcon } from 'lucide-solid'
export const Basic = () => (