- ` or `
- ` elements correctly within `
- ` or `
- ` elements correctly within `
- ` or `
- Click to select single item
- Ctrl/Cmd + Click to toggle individual items
- Shift + Click to select range from first selected item
- {{ item }}
- `.
- **Textarea**: Fixed `ResizeObserver` warning.
- **Timer**: Fixed stopping issue when switching tabs; resolved issue where `action` prop was passed to `ActionTrigger`.
- **Toast**: Fixed keyboard navigation skipping close button.
- **Toggle Group**: Fixed `data-focus` not being removed on blur.
# About
## Acknowledgments
We are committed to open source and the power of collaboration. Our work has been inspired by numerous projects and
individuals who continually drive us to innovate and improve.
- [Zag.js](https://zagjs.com/) - The foundation of this project
- [Park UI](https://park-ui.com) - For providing the styled component demos featured in this project
- [Radix Vue](https://www.radix-vue.com/) - For `useForwardPropsEmits`, which we re-export to build closed Vue
components
## License
This project is licensed under the terms of the [MIT license](https://github.com/chakra-ui/ark/blob/main/LICENSE).
# GUIDES
---
# Animation
Adding animation to Ark UI Components is as straightforward as with any other component, but keep in mind some
considerations when working with exit animations with JavaScript animation libraries.
## Animating with CSS
The most straightforward method to animate your elements is using CSS. You can animate both the mounting and unmounting
phases with CSS. The latter is achievable because Ark UI Components postpones the unmounting while your animation runs.
Below is a simple example of creating a fade-in and fade-out animation using CSS keyframes:
```css
@keyframes fadeIn {
from {
opacity: 0;
}
to {
opacity: 1;
}
}
@keyframes fadeOut {
from {
opacity: 1;
}
to {
opacity: 0;
}
}
```
You can use these keyframes to animate any element during its lifecycle. For instance, to apply the `fadeIn` animation
when your `Tooltip` enters the 'open' state, and `fadeOut` when it enters the 'closed' state, you could use the
following styles:
```css
[data-scope='tooltip'][data-part='content'][data-state='open'] {
animation: fadeIn 300ms ease-out;
}
[data-scope='tooltip'][data-part='content'][data-state='closed'] {
animation: fadeOut 300ms ease-in;
}
```
## Animating with JS Libraries
There's plenty of versatility when it comes to animating your Ark UI Elements with JavaScript libraries. Various
libraries such as GreenSock, anime.js, Framer Motion, and more can add a new level of interaction and feedback to your
UI components.
One significant advantage of using Ark UI Elements is the control you have over the unmounting phase of your components.
This is primarily facilitated through the `present` prop. The `present` prop allows the component to stay mounted even
after its enclosing condition has been falsified, allowing for exit animations to complete before the component is
removed from the DOM.
# Closed Components
## Motivation
Writing a few lines of code every time you need a simple `Avatar` is tedious. Creating a dedicated component
encapsulates logic, simplifies the API, ensures consistent usage, and maintains clean code. This approach enhances
reusability, making the component easier to maintain and test.
Here's an example of an `Avatar` component that can be used consistently across your application:
```vue
{{ getInitials }} ``` # 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 SA Segun Adebayo is online (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{/* … */} {/* … */} {/* … */} 
It works with tools like Claude Code, Cursor, and Copilot to generate code and apply design system logic consistently
across React, Vue, Solid, and Svelte.
## Tools
The Ark UI MCP exposes the following tools to AI agents:
- **`list_components`**: Returns a full list of all available components
- **`list_examples`**: Lists various component examples
- **`get_example`**: Retrieves code examples and usage patterns
- **`styling_guide`**: Provides styling guidelines for components (data attributes and CSS variables)
## Setup
The MCP server currently supports only
[stdio transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio) and is published at
`@ark-ui/mcp`.
### Visual Studio Code
> Make sure you have the [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) and
> [GitHub Copilot Chat](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat) extensions installed.
- In the `.vscode/mcp.json` file at the root of your project, add the MCP server block:
```json title=".vscode/mcp.json"
{
"servers": {
"ark-ui": {
"command": "npx",
"args": ["-y", "@ark-ui/mcp"]
}
}
}
```
- The MCP server is now ready to use. Click the **"Start"** button in the `mcp.json` file.
- Start a new chat VSCode Copilot like _"Build me a checkbox with ark ui"_
### Cursor
- In the `.cursor/mcp.json` file at the root of your project, add the following configuration:
```json
{
"mcpServers": {
"ark-ui": {
"command": "npx",
"args": ["-y", "@ark-ui/mcp"]
}
}
}
```
- Go to **Settings** > **Cursor Settings** > **MCP & Integrations** and enable the Ark UI server.
- Start a new chat Cursor chat like _"Build me a checkbox with ark ui"_
### Claude Code
> Make sure you have Claude Code installed. Visit [Anthropic docs](https://docs.anthropic.com/en/docs/claude-code/mcp)
> for installation instructions.
- Run the following command in your terminal to add the Ark UI MCP server:
```bash
claude mcp add ark-ui -- npx -y @ark-ui/mcp
```
- Start a Claude Code session by running `claude`
- Type a prompt like _"Build me a checkbox with ark ui"_
### Windsurf
- Navigate to **Settings** > **Windsurf Settings** > **Cascade**
- Click the **Manage MCPs** button, then click the **"View raw config"** button.
- Add the following to the MCP configuration file:
```json title=".codeium/windsurf/mcp_config.json"
{
"mcpServers": {
"ark-ui": {
"command": "npx",
"args": ["-y", "@ark-ui/mcp"]
}
}
}
```
> You might need to click the **Refresh** button to see the MCP server in the list.
- Start a new chat Windsurf like _"Build me a checkbox with ark ui"_
### Zed
- Go to **Settings** > **Open Settings**
- In the `settings.json` file, add MCP server as a new **context server**:
```json title=".config/zed/settings.json"
{
"context_servers": {
"ark-ui": {
"source": "custom",
"command": "npx",
"args": ["-y", "@ark-ui/mcp"]
}
}
}
```
- Start a new chat Zed like _"Build me a checkbox with ark ui"_
### Custom MCP Client
To run the MCP server in a local or development environment using a custom MCP client, you need to add the MCP server to
the client's configuration file.
```json
{
"mcpServers": {
"ark-ui": {
"command": "npx",
"args": ["-y", "@ark-ui/mcp"]
}
}
}
```
# COLLECTIONS
---
# Async List
The `useAsyncList` hook manages asynchronous data operations for list collections. It provides a comprehensive solution
for loading, filtering, sorting, and paginating data with built-in loading states, error handling, and request
cancellation.
```tsx
import { useAsyncList } from '@ark-ui/react/collection'
const list = useAsyncList({ async load({ signal }) { const response = await fetch('/api/users', { signal }) const users = await response.json() return { items: users } }, }) console.log(list.items) // User[] console.log(list.loading) // boolean console.log(list.error) // Error | null ``` ## Examples ### Basic Usage The most basic usage involves providing a `load` function that returns data. ```vue ``` ### Infinite Loading Implement pagination by returning a cursor that indicates more data is available. ```vueError: {{ list.error.message }}"{{ quote.quote }}"— {{ quote.author }}``` ### Filtering Filter data based on user input with automatic debouncing and loading states. ```vueLoaded {{ list.items.length }} posts (more available)Error: {{ list.error.message }}{{ index + 1 }}: {{ post.title }}{{ post.body }}``` ### Sorting (Client-side) Sort data on the client side after loading from the server. ```vueLoading...Error: {{ list.error.message }}{{ user.name }}{{ user.email }}{{ user.department }} • {{ user.role }}No results found``` ### Sorting (Server-side) Send sort parameters to the server and reload data when sorting changes. ```vueLoading...Error: {{ list.error.message }}Sorted by: {{ descriptor ? `${descriptor.column} (${descriptor.direction})` : 'none' }}{{ label }} {{ getSortIcon(key as keyof User) }} {{ user.name }} {{ user.username }} {{ user.email }} {{ user.phone }} {{ user.website }} ``` ### Dependencies Automatically reload data when dependencies change, such as filter selections or external state. ```vueLoading...Error: {{ list.error.message }}{{ product.title }}${{ product.price }}{{ product.category }}{{ product.rating.rate }} ({{ product.rating.count }} reviews)Sorted by {{ list.sortDescriptor.column }} ({{ list.sortDescriptor.direction }})``` ## API Reference ### Props - **load** (`(params: LoadParamsDependencies Example
Loading...Error: {{ list.error.message }}Found {{ list.items.length }} users{{ user.name }}{{ user.email }}{{ user.department }} • {{ user.role }}No users found with current filters) => Promise ) => Promise `) - Optional function for client-side sorting - **autoReload** (`boolean`, default: `false`) - Whether to automatically reload data on mount - **initialItems** (`T[]`, default: `[]`) - Initial items to display before first load - **dependencies** (`any[]`, default: `[]`) - Values that trigger a reload when changed - **initialFilterText** (`string`, default: `''`) - Initial filter text value - **initialSortDescriptor** (`SortDescriptor | null`) - Initial sort configuration ### Load Parameters The `load` function receives an object with the following properties: - **cursor** (`C | undefined`) - Current cursor for pagination - **filterText** (`string`) - Current filter text - **sortDescriptor** (`SortDescriptor | null`) - Current sort configuration - **signal** (`AbortSignal`) - AbortController signal for request cancellation ### Load Result The `load` function should return an object with: - **items** (`T[]`) - The loaded items - **cursor** (`C | undefined`) - Optional cursor for next page ### Sort Parameters The `sort` function receives an object with: - **items** (`T[]`) - Current items to sort - **descriptor** (`SortDescriptor`) - Sort configuration with `column` and `direction` ### Return Value The hook returns an object with the following properties and methods: #### State Properties - **items** (`T[]`) - Current list of items - **loading** (`boolean`) - Whether a load operation is in progress - **error** (`Error | null`) - Any error from the last operation - **cursor** (`C | undefined`) - Current cursor for pagination - **filterText** (`string`) - Current filter text - **sortDescriptor** (`SortDescriptor | null`) - Current sort configuration #### Methods - **reload** (`() => void`) - Reload data from the beginning - **loadMore** (`() => void`) - Load more items (when cursor is available) - **setFilterText** (`(text: string) => void`) - Set filter text and reload - **sort** (`(descriptor: SortDescriptor) => void`) - Apply sorting #### Types ```tsx interface SortDescriptor { column: string direction: 'ascending' | 'descending' } interface LoadParams { cursor?: C filterText: string sortDescriptor?: SortDescriptor | null signal: AbortSignal } interface LoadResult ``` ### Multiple Selection Set `selectionMode` to `multiple` to allow multiple items to be selected. ```vue{{ JSON.stringify(selection.selectedValues.value) }}``` ### Range Selection Here's an example of how to implement range selection that extends the selection from the first selected item to the clicked item. ```vue{{ selection.selectedValues.value.length }} of {{ collection.items.length }} selected``` ## API Reference ### Props - **collection** (`ListCollectionInstructions:
{{ item.label }}`) - The collection to manage selection for - **selectionMode** (`'single' | 'multiple' | 'none'`, default: `'single'`) - The selection mode - **deselectable** (`boolean`, default: `true`) - Whether selected items can be deselected - **initialSelectedValues** (`string[]`, default: `[]`) - Initial selected values - **resetOnCollectionChange** (`boolean`, default: `false`) - Whether to reset selection when collection changes ### Return Value The hook returns an object with the following properties and methods: #### State Properties - **selectedValues** (`string[]`) - Array of currently selected values - **isEmpty** (`boolean`) - Whether no items are selected - **firstSelectedValue** (`string | null`) - The first selected value in collection order - **lastSelectedValue** (`string | null`) - The last selected value in collection order #### Query Methods - **isSelected** (`(value: string | null) => boolean`) - Check if a value is selected - **canSelect** (`(value: string) => boolean`) - Check if a value can be selected - **isAllSelected** (`() => boolean`) - Check if all items are selected - **isSomeSelected** (`() => boolean`) - Check if some items are selected #### Selection Methods - **select** (`(value: string, forceToggle?: boolean) => void`) - Select a value - **deselect** (`(value: string) => void`) - Deselect a value - **toggle** (`(value: string) => void`) - Toggle selection of a value - **replace** (`(value: string | null) => void`) - Replace selection with a single value - **extend** (`(anchorValue: string, targetValue: string) => void`) - Extend selection from anchor to target - **setSelectedValues** (`(values: string[]) => void`) - Set the selected values - **setSelection** (`(values: string[]) => void`) - Set the selection (alias for setSelectedValues) - **clear** (`() => void`) - Clear all selections - **resetSelection** (`() => void`) - Reset selection to initial state # Tree Collection A tree collection is designed to manage hierarchical data structures like file systems, navigation menus, or organization charts. It provides powerful methods for traversing, manipulating, and querying tree structures. ```ts import { createTreeCollection } from '@ark-ui/react/collection' const treeData = { value: 'root', label: 'Root', children: [ { value: 'folder1', label: 'Folder 1', children: [ { value: 'file1', label: 'File 1.txt' }, { value: 'file2', label: 'File 2.txt' }, ], }, { value: 'folder2', label: 'Folder 2', children: [ { value: 'subfolder1', label: 'Subfolder 1', children: [{ value: 'file3', label: 'File 3.txt' }], }, ], }, ], } const tree = createTreeCollection({ rootNode: treeData }) ``` ### Navigation Methods The tree collection provides various methods to navigate through the hierarchical structure. #### Getting First and Last Nodes ```ts const firstNode = tree.getFirstNode() console.log(firstNode?.value) // "folder1" const lastNode = tree.getLastNode() console.log(lastNode?.value) // "folder2" ``` #### Sequential Navigation Navigate to the next or previous node in the tree traversal order: ```ts const nextNode = tree.getNextNode('file1') console.log(nextNode?.value) // "file2" const previousNode = tree.getPreviousNode('file2') console.log(previousNode?.value) // "file1" ``` ### Hierarchical Relationships #### Parent and Children Get parent and descendant nodes: ```ts // Get parent node const parentNode = tree.getParentNode('file1') console.log(parentNode?.value) // "folder1" // Get all ancestor nodes const ancestors = tree.getParentNodes('file3') console.log(ancestors.map((n) => n.value)) // ["folder2", "subfolder1"] // Get all descendant nodes const descendants = tree.getDescendantNodes('folder1') console.log(descendants.map((n) => n.value)) // ["file1", "file2"] // Get descendant values only const descendantValues = tree.getDescendantValues('folder2') console.log(descendantValues) // ["subfolder1", "file3"] ``` #### Sibling Navigation Navigate between sibling nodes: ```ts // Assuming we have the index path of "file1" const indexPath = tree.getIndexPath('file1') // [0, 0] const nextSibling = tree.getNextSibling(indexPath) console.log(nextSibling?.value) // "file2" const previousSibling = tree.getPreviousSibling(indexPath) console.log(previousSibling) // undefined (no previous sibling) // Get all siblings const siblings = tree.getSiblingNodes(indexPath) console.log(siblings.map((n) => n.value)) // ["file1", "file2"] ``` ### Index Path Operations Work with index paths to identify node positions: ```ts // Get index path for a value const indexPath = tree.getIndexPath('file3') console.log(indexPath) // [1, 0, 0] // Get value from index path const value = tree.getValue([1, 0, 0]) console.log(value) // "file3" // Get full value path (all ancestors + node) const valuePath = tree.getValuePath([1, 0, 0]) console.log(valuePath) // ["folder2", "subfolder1", "file3"] // Get node at specific index path const node = tree.at([1, 0]) console.log(node?.value) // "subfolder1" ``` ### Tree Queries #### Branch and Leaf Detection ```ts // Check if a node is a branch (has children) const folder1Node = tree.findNode('folder1') const isBranch = tree.isBranchNode(folder1Node!) console.log(isBranch) // true // Get all branch values const branchValues = tree.getBranchValues() console.log(branchValues) // ["folder1", "folder2", "subfolder1"] ``` #### Tree Traversal Visit all nodes with custom logic: ```ts tree.visit({ onEnter: (node, indexPath) => { console.log(`Visiting: ${node.value} at depth ${indexPath.length}`) // Skip certain branches if (node.value === 'folder2') { return 'skip' // Skip this branch and its children } }, }) ``` #### Filtering Create a new tree with filtered nodes: ```ts // Keep only nodes that match criteria const filteredTree = tree.filter((node, indexPath) => { return node.value.includes('file') // Only keep files }) console.log(filteredTree.getValues()) // ["file1", "file2", "file3"] ``` ### Tree Manipulation #### Adding Nodes ```ts const newFile = { value: 'newfile', label: 'New File.txt' } // Insert after a specific node const indexPath = tree.getIndexPath('file1') const updatedTree = tree.insertAfter(indexPath!, [newFile]) // Insert before a specific node const updatedTree2 = tree.insertBefore(indexPath!, [newFile]) ``` #### Removing Nodes ```ts const indexPath = tree.getIndexPath('file2') const updatedTree = tree.remove([indexPath!]) console.log(updatedTree.getValues()) // file2 is removed ``` #### Moving Nodes ```ts const fromIndexPaths = [tree.getIndexPath('file1')!] const toIndexPath = tree.getIndexPath('folder2')! const updatedTree = tree.move(fromIndexPaths, toIndexPath) // file1 is now moved under folder2 ``` #### Replacing Nodes ```ts const indexPath = tree.getIndexPath('file1')! const newNode = { value: 'replacedfile', label: 'Replaced File.txt' } const updatedTree = tree.replace(indexPath, newNode) ``` ### Utility Methods #### Flattening Convert the tree to a flat structure: ```ts const flatNodes = tree.flatten() console.log(flatNodes.map((n) => ({ value: n.value, depth: n._indexPath.length }))) // [{ value: "folder1", depth: 1 }, { value: "file1", depth: 2 }, ...] ``` #### Getting All Values ```ts const allValues = tree.getValues() console.log(allValues) // ["folder1", "file1", "file2", "folder2", "subfolder1", "file3"] ``` #### Depth Calculation ```ts const depth = tree.getDepth('file3') console.log(depth) // 3 (root -> folder2 -> subfolder1 -> file3) ``` ### Working with Custom Node Types You can customize how the tree collection interprets your data: ```ts interface CustomNode { id: string name: string items?: CustomNode[] isDisabled?: boolean } const customTree = createTreeCollection ({ rootNode: { id: 'root', name: 'Root', items: [ { id: '1', name: 'Item 1', isDisabled: false }, { id: '2', name: 'Item 2', isDisabled: true }, ], }, nodeToValue: (node) => node.id, nodeToString: (node) => node.name, nodeToChildren: (node) => node.items, isNodeDisabled: (node) => node.isDisabled ?? false, }) ``` ### Creating Trees from File Paths Create a tree structure from file paths: ```ts import { createFileTreeCollection } from '@ark-ui/react/collection' const paths = ['src/components/Button.tsx', 'src/components/Input.tsx', 'src/utils/helpers.ts', 'docs/README.md'] const fileTree = createFileTreeCollection(paths) console.log(fileTree.getBranchValues()) // ["src", "components", "utils", "docs"] ``` > **Good to know**: Tree collections are immutable - all modification methods return a new tree instance rather than > modifying the original. # COMPONENTS --- # Accordion ## Features - Full keyboard navigation - Supports horizontal and vertical orientation - Right-to-Left (RTL) support - Single or multiple item expansion - Controlled and uncontrolled modes - Collapse each accordion item ## Anatomy To set up the accordion correctly, it's essential to understand its anatomy and the naming of its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples ### Default Expanded State Set the `defaultValue` prop to specify which item should be expanded by default. ```vue 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 {{ clipboard.copied ? 'Copied!' : 'Copy' }} Value: {{ clipboard.value }} Copied {{ copyCount }} times
Copy this link Copy this link Copy this link (5 second timeout) ` 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 }} ✓ Open Clear Frameworks + Create "{{ item.label }}" {{ item.label }} {{ item.__new__ ? NEW_OPTION_VALUE : '' }} ✓ Open Clear Countries {{ item.country }} ✓ ; /* 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: `'none' | 'autocomplete' | '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-nested`**: listbox **`data-has-nested`**: listbox **`data-placement`**: The placement of the content **`data-empty`**: Present when the content is 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 ### Empty #### 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. ### 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`**: Present when the content is 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`**: Present when the content is 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 Length Use the `maxLength` prop to set a maximum number of characters that can be entered into the editable. ```tsx{/*...*/} ``` ### Double click activation The editable supports two modes of activating the "edit" state: - when the preview part is focused (with pointer or keyboard). - when the preview part is double-clicked. To change the mode to double-click, pass the prop `activationMode="dblclick"`. ```tsx{/*...*/} ``` ### 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 Any Control Uses getControlProps() for maximum flexibility This field has an error 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 Choose file(s) Generic IconX File Upload Choose file(s) 📄File Upload Choose file(s) Clear Files Drag and drop your images here Upload Folder {{ file.webkitRelativePath ?? file.name }} File Upload (PNG and JPEG only) Drop your files here Select Files Remove {{ error }}File Upload with Validation Select Files ✅ Accepted Files
No files uploaded yetPDFRemove ❌ Rejected Files
No rejected filesValidation Errors:{{ errorMessages[error] || `❓ ${error}` }}File Upload with Compression Choose Images Remove Choose file(s) X Label Select Additional Info Error Info File Upload Drop your files here Choose file(s) Generic IconX File Upload with Paste X {/* ... */} ``` ### Prevent document drop By default, when the dropzone is active, we prevent accidental navigation when files are dropped outside the dropzone. To prevent this behavior, set the `preventDocumentDrop` prop to `false`. ```tsx{/* ... */} ``` ### Prevent double open When you want to delegate clicking to the trigger and remove the dropzone from the tab order, you can use the `disableClick` prop. This prevents the the file picker from opening twice. ```tsxChoose Files Drag files here` 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`**: The id the active descendant of the content **`data-orientation`**: The orientation of the content **`data-layout`**: **`data-empty`**: Present when the content is empty ### Empty #### Props **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. ### 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`**: Present when the content is 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 ` element and displays a custom cursor element during scrubbing interactions. This component utilizes the [Pointer Lock API](https://developer.mozilla.org/en-US/docs/Web/API/Pointer_Lock_API) for smooth dragging interactions. > **Note:** Browsers may show a notification when the Pointer Lock API is activated. The scrubber is automatically > disabled in Safari to prevent layout shifts. ## API Reference ### Root #### Props **`allowMouseWheel`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether to allow mouse wheel to change the value **`allowOverflow`** Type: `boolean` Required: false Default Value: `true` Description: Whether to allow the value overflow the min/max range **`asChild`** Type: `boolean` Required: false Default Value: `undefined` Description: Use the provided child element as the default rendered element, combining their props and behavior. **`clampValueOnBlur`** Type: `boolean` Required: false Default Value: `true` Description: Whether to clamp the value when the input loses focus (blur) **`defaultValue`** Type: `string` Required: false Default Value: `undefined` Description: The initial value of the input when rendered. Use when you don't need to control the value of the input. **`disabled`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether the number input is disabled. **`focusInputOnChange`** Type: `boolean` Required: false Default Value: `true` Description: Whether to focus input when the value changes **`form`** Type: `string` Required: false Default Value: `undefined` Description: The associate form of the input element. **`formatOptions`** Type: `NumberFormatOptions` Required: false Default Value: `undefined` Description: The options to pass to the `Intl.NumberFormat` constructor **`id`** Type: `string` Required: false Default Value: `undefined` Description: The unique identifier of the machine. **`ids`** Type: `Partial<{ root: string label: string input: string incrementTrigger: string decrementTrigger: string scrubber: string }>` Required: false Default Value: `undefined` Description: The ids of the elements in the number input. Useful for composition. **`inputMode`** Type: `'text' | 'tel' | 'numeric' | 'decimal'` Required: false Default Value: `"decimal"` Description: Hints at the type of data that might be entered by the user. It also determines the type of keyboard shown to the user on mobile devices **`invalid`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether the number input value is invalid. **`locale`** Type: `string` Required: false Default Value: `"en-US"` Description: The current locale. Based on the BCP 47 definition. **`max`** Type: `number` Required: false Default Value: `Number.MAX_SAFE_INTEGER` Description: The maximum value of the number input **`min`** Type: `number` Required: false Default Value: `Number.MIN_SAFE_INTEGER` Description: The minimum value of the number input **`modelValue`** Type: `string` Required: false Default Value: `undefined` Description: The v-model value of the number input **`name`** Type: `string` Required: false Default Value: `undefined` Description: The name attribute of the number input. Useful for form submission. **`pattern`** Type: `string` Required: false Default Value: `"[0-9]*(.[0-9]+)?"` Description: The pattern used to check the element's value against **`readOnly`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether the number input is readonly **`required`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether the number input is required **`spinOnPress`** Type: `boolean` Required: false Default Value: `true` Description: Whether to spin the value when the increment/decrement button is pressed **`step`** Type: `number` Required: false Default Value: `1` Description: The amount to increment or decrement the value by **`translations`** Type: `IntlTranslations` Required: false Default Value: `undefined` Description: Specifies the localized strings that identifies the accessibility elements and their states #### Emits **`focusChange`** Type: `[details: FocusChangeDetails]` Description: Function invoked when the number input is focused **`update:modelValue`** Type: `[value: string]` Description: The callback fired when the model value changes. **`valueChange`** Type: `[details: ValueChangeDetails]` Description: Function invoked when the value changes **`valueInvalid`** Type: `[details: ValueInvalidDetails]` Description: Function invoked when the value overflows or underflows the min/max range #### Data Attributes **`data-scope`**: number-input **`data-part`**: root **`data-disabled`**: Present when disabled **`data-focus`**: Present when focused **`data-invalid`**: Present when invalid **`data-scrubbing`**: ### Control #### Props **`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`**: control **`data-focus`**: Present when focused **`data-disabled`**: Present when disabled **`data-invalid`**: Present when invalid **`data-scrubbing`**: ### DecrementTrigger #### 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`**: decrement-trigger **`data-disabled`**: Present when disabled **`data-scrubbing`**: ### IncrementTrigger #### 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`**: increment-trigger **`data-disabled`**: Present when disabled **`data-scrubbing`**: ### 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`**: number-input **`data-part`**: input **`data-invalid`**: Present when invalid **`data-disabled`**: Present when disabled **`data-scrubbing`**: ### 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`**: number-input **`data-part`**: label **`data-disabled`**: Present when disabled **`data-focus`**: Present when focused **`data-invalid`**: Present when invalid **`data-scrubbing`**: ### RootProvider #### Props **`value`** Type: `NumberInputApi` 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 **`data-scrubbing`**: ### 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 **`data-scrubbing`**: ## 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 Page {{ pagination.page }} of {{ pagination.totalPages }}
Items {{ pagination.pageRange.start + 1 }}-{{ pagination.pageRange.end }}
Current Page Items:
Previous {{ page.value }} … Next Previous {{ page.value }} … Next Showing {{ pagination.pageRange.start + 1 }}-{{ pagination.pageRange.end }} of {{ pagination.count }} results
Page {{ pagination.page }} of {{ pagination.totalPages }}
Previous {{ page.value }} … Next Page {{ pagination.page }} of {{ pagination.totalPages }}
Previous {{ page.value }} … Next ``` ### Root Provider The `RootProvider` component provides a context for the pagination. It accepts the value of the `usePagination` hook. You can leverage it to access the component state and methods from outside the pagination. ```vuePrevious 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 **`requestDismiss`** Type: `[ event: CustomEvent<{ originalLayer: HTMLElement targetLayer: HTMLElement | undefined originalIndex: number targetIndex: number }>, ]` Description: Function called when this layer is closed due to a parent layer being closed **`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-nested`**: popover **`data-has-nested`**: popover **`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. ## 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. # Scroll Area ## Features - Cross-browser custom scrollbars - Native scroll behavior - Keyboard navigation support - Touch and mouse support - Horizontal and vertical scrolling - Support for nested scroll areas - Customizable scrollbar appearance ## Anatomy To set up the scroll area correctly, it's essential to understand its anatomy and the naming of its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Required style It's important to note that the scroll area requires the following styles on the `ScrollArea.Viewport` element to hide the native scrollbar: ```css [data-scope='scroll-area'][data-part='viewport'] { scrollbar-width: none; &::-webkit-scrollbar { display: none; } } ``` ## Examples ### Basic Usage Create a basic scrollable area with custom scrollbar. ```vue Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem.
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt.
At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis praesentium voluptatum deleniti atque corrupti quos dolores et quas molestias excepturi sint occaecati cupiditate non provident, similique sunt in culpa qui officia deserunt mollitia animi, id est laborum et dolorum fuga.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
This is a nested scroll area. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.
Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem.
` 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. ### Scrollbar #### 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. **`orientation`** Type: `Orientation` Required: false Default Value: `undefined` Description: undefined #### Data Attributes **`data-scope`**: scroll-area **`data-part`**: scrollbar **`data-orientation`**: The orientation of the scrollbar **`data-scrolling`**: Present when scrolling **`data-hover`**: Present when hovered **`data-dragging`**: Present when in the dragging state **`data-overflow-x`**: Present when the content overflows the x-axis **`data-overflow-y`**: Present when the content overflows the y-axis ### Thumb #### Props **`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`**: scroll-area **`data-part`**: thumb **`data-orientation`**: The orientation of the thumb **`data-hover`**: Present when hovered **`data-dragging`**: Present when in the dragging state ### Viewport #### Props **`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`**: scroll-area **`data-part`**: viewport **`data-at-top`**: Present when scrolled to the top edge **`data-at-bottom`**: Present when scrolled to the bottom edge **`data-at-left`**: Present when scrolled to the left edge **`data-at-right`**: Present when scrolled to the right edge **`data-overflow-x`**: Present when the content overflows the x-axis **`data-overflow-y`**: Present when the content overflows the y-axis # 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-nested`**: listbox **`data-has-nested`**: listbox **`data-placement`**: The placement of the content **`data-activedescendant`**: The id the active descendant of the content ### 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 ``` ### Promise You can use `toaster.promise()` to automatically handle the different states of an asynchronous operation. It provides options for the `success`, `error`, and `loading` states of the promise and will automatically update the toast when the promise resolves or rejects. ```vue{{ toast.title }} {{ toast.description }} ``` ### Update Toast To update a toast, use the `toast.update` method. ```vue{{ toast.title }} {{ toast.description }} ``` ### Action To add an action to a toast, use the `toast.action` property. ```vue{{ toast.title }} {{ toast.description }} ``` ### Custom Duration You can control how long a toast stays visible by setting a custom `duration` in milliseconds, or use `Infinity` to keep it visible until manually dismissed. ```vue{{ toast.title }} {{ toast.description }} {{ toast.action?.label }} ``` ### Maximum Visible Toasts Set the `max` prop on the `createToaster` function to define the maximum number of toasts that can be rendered at any one time. Any extra toasts will be queued and rendered when a toast has been dismissed. ```vue{{ toast.title }} {{ toast.description }} ``` ## Guides ### Creating Toast in Effects When creating a toast inside React effects (like `useEffect`, `useLayoutEffect`, or event handlers that trigger during render), you may encounter a "flushSync" warning. To avoid this, wrap the toast call in `queueMicrotask`: ```tsx import { useEffect } from 'react' export const EffectToast = () => { useEffect(() => { // ❌ This may cause flushSync warnings // toaster.create({ title: 'Effect triggered!' }) // ✅ Wrap in queueMicrotask to avoid warnings queueMicrotask(() => { toaster.create({ title: 'Effect triggered!', description: 'This toast was called safely from an effect', type: 'success', }) }) }, []) return{{ toast.title }} {{ toast.description }} Component content} ``` This ensures the toast creation is deferred until after the current execution context, preventing React's concurrent rendering warnings. ### Styling the toast There's a minimal styling required for the toast to work correctly. #### Toast root The toast root will be assigned these css properties at runtime: - `--x` - The x position - `--y` - The y position - `--scale` - The scale - `--z-index` - The z-index - `--height` - The height - `--opacity` - The opacity - `--gap` - The gap between toasts ```css [data-scope='toast'][data-part='root'] { translate: var(--x) var(--y); scale: var(--scale); z-index: var(--z-index); height: var(--height); opacity: var(--opacity); will-change: translate, opacity, scale; transition: translate 400ms, scale 400ms, opacity 400ms, height 400ms, box-shadow 200ms; transition-timing-function: cubic-bezier(0.21, 1.02, 0.73, 1); &[data-state='closed'] { transition: translate 400ms, scale 400ms, opacity 200ms; transition-timing-function: cubic-bezier(0.06, 0.71, 0.55, 1); } } ``` #### Styling based on type You can also style based on the `data-type` attribute. ```css [data-scope='toast'][data-part='root'] { &[data-type='error'] { background: red; color: white; } &[data-type='info'] { background: blue; color: white; } &[data-type='warning'] { background: orange; } &[data-type='success'] { background: green; color: white; } } ``` #### Mobile considerations A very common use case is to adjust the toast width on mobile so it spans the full width of the screen. ```css @media (max-width: 640px) { [data-scope='toast'][data-part='group'] { width: 100%; } [data-scope='toast'][data-part='root'] { inset-inline: 0; width: calc(100% - var(--gap) * 2); } } ``` ## 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: ```vueA 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-nested`**: popover **`data-has-nested`**: popover **`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. **`checkedValue`** Type: `string[]` Required: false Default Value: `undefined` Description: The controlled checked node values **`defaultCheckedValue`** Type: `string[]` Required: false Default Value: `undefined` Description: The initial checked node values when rendered. Use when you don't need to control the checked node values. **`defaultExpandedValue`** Type: `string[]` Required: false Default Value: `undefined` Description: The initial expanded node values when rendered. Use when you don't need to control the expanded node values. **`defaultFocusedValue`** Type: `string` Required: false Default Value: `undefined` Description: The initial focused node value when rendered. Use when you don't need to control the focused node value. **`defaultSelectedValue`** Type: `string[]` Required: false Default Value: `undefined` Description: The initial selected node values when rendered. Use when you don't need to control the selected node values. **`expandedValue`** Type: `string[]` Required: false Default Value: `undefined` Description: The controlled expanded node values **`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 **`loadChildren`** Type: `(details: LoadChildrenDetails ) => Promise ` 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 ```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 ``` ### Exact Match By default, the Highlight component matches partial words. Use the `exactMatch` prop to only highlight whole words that match the query exactly. ```vueMatch All
Match First Occurrence Only
``` ## 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 **`exactMatch`** Type: `boolean` Required: false Default Value: `undefined` Description: Whether to match the exact query **`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. ```tsxWithout exactMatch (highlights partial matches):
With exactMatch (highlights whole words only):
``` Style the `mark` tags using CSS to customize the appearance of highlighted text. ```css .highlighted-text { background-color: yellow; } ``` # JSON Tree View ## Anatomy To set up the JSON tree view 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 `JsonTreeView` component in your project. Let's take a look at the most basic example: ```vue {{ node.value }} } />
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. # 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]
## [5.9.0] - 2025-09-11
### Added
- **Dismissable**: Add support for layer types in dismissable layer stack. Layers can now be categorized as `dialog`,
`popover`, `menu`, or `listbox`. This enables:
- `data-nested` attribute on nested layers of the same type
- `data-has-nested` attribute on parent layers with nested children of the same type
- `--nested-layer-count` CSS variable indicating the number of nested layers of the same type
### Fixed
- **Menu**: Fix issue where hovering a partially visible item with pointer causes it to scroll into view
- **Tabs**: Fix issue where `ids` for `item` and `content` could not be customized
- **Toast**: Allow creating a toast store without any arguments
## [5.8.0] - 2025-09-08
### Added
- **Field**: Add `data-required` attribute to `Field.Label`
- **Select, Combobox, Listbox, TreeView**: Export `RootComponent` and `RootProviderComponent` types which are useful
when building compositions that wrap the `Root` and `RootProvider` components and you still want type-safety for the
collection.
### Fixed
- **Menu**: Fix `Menu.ItemText` not working inside `Menu.TriggerItem`
## [5.7.0] - 2025-08-28
### Added
- **Combobox**: Add `ComboboxEmpty` component to display content when the combobox has no items
- **Listbox**: Add `ListboxEmpty` component to display content when the listbox has no items
- **Hover Card**: Add support for `disabled` prop
### Fixed
- **Collection**: Fix issue where disabled items could be reached via typeahead
- **Color Picker**: Fix issue where color picker was not working correctly in RTL mode
- **Date Picker**: Fix issue where datepicker doesn't revert to a valid value when the input value exceeds the min/max
and blurred
- **Dismissable**: Expose `onRequestDismiss` custom event handler for event a parent layer requests the child layer to
dismiss. If prevented via `event.preventDefault()`, the child layer will not dismiss when the parent layer is
dismissed.
- **Number Input**
- Omit the input `pattern` when `formatOptions` is provided. This prevents native pattern validation from conflicting
with formatted values (e.g., currency or percent).
- Handle empty values consistently across all format options.
- Add `data-scrubbing` attribute to the number input parts.
- **Tags Input**: Fix issue where highlighted item doesn't clear when tabbing out of the input to an external button
within the `control` part.
- **Tooltip**
- Set `closeOnPointerdown` to `false` when `closeOnClick` is set to `false`
- Reduce bundle size by replacing `@zag-js/store` dependency with a lightweight store implementation.
## [5.6.0] - 2025-08-24
### Added
- **Functions**: Add `useAsyncList` and `useCollator` functions for managing asynchronous list operations and
locale-aware string comparison
- **Toast**: Export type definitions `ToastActionOptions`, `ToastPlacement`, `ToastPromiseOptions`, `ToastStatus`,
`ToastStatusChangeDetails`, and `ToastType`
### Changed
- **Fieldset**
- Update Legend component to render as `div` instead of `legend` element for improved styling flexibility
- Add `aria-labelledby` attribute to fieldset root for better accessibility by linking to legend
### Fixed
- **Date Picker**
- Clear hovered range state after completing range selection instead of waiting for pointer to leave the calendar
area.
- Fix issue where month and year select labels don't update correctly when using `min`/`max` constraints.
- Expose `disabled` on `api.getMonths()` and `api.getYears()` results to indicate options out of range for current
constraints.
- **Listbox**
- Fix issue where first enabled item should be highlighted by default when listbox receives focus and no item is
currently highlighted.
- Add `getElement` to `scrollToIndexFn` details
- Track collection changes and clear `highlightedValue` if the item is no longer in the collection.
- **ScrollArea**
- Avoid detecting hover state from portalled descendants.
- Add `data-dragging` attribute to scroll area parts.
- **Select**: Add `getElement` to `scrollToIndexFn` details
- **Combobox**: Add `getElement` to `scrollToIndexFn` details
## [5.5.0] - 2025-08-20
### Added
- **Highlight Word**: Add `exactMatch` option that enables whole-word matching using regex word boundaries.
### Fixed
- **Menu**: Fix context menu repositioning logic
- **Scroll Area**: Add `data-hover` to scroll area
## [5.4.0] - 2025-08-18
### Added
- **ScrollArea [NEW]**: Add support for new scroll area component.
### Fixed
- **ListCollection**
- Avoid recomputing groups on every call to `at()` and `indexOf()`
- Fixed bug in `find()` method (was checking `!= null` instead of `!== -1`)
- **GridCollection**: Avoid recomputing rows on every call to `getRows()`
- **Menu**
- Add `data-state` attribute for context menu trigger
- Fix context menu positioning bug where reopening at the same coordinates fails to reposition
## [5.3.4] - 2025-08-14
### Fixed
- **Listbox**: Add support for navigating grid collections
- **Carousel**:
- Fix an issue where the carousel would not update when `slideCount` or `autoplay` props change.
- Fix an issue where `loop: false` was ignored when using autoplay. Now, the carousel will stop when it gets to the
last slide.
- **Date Picker**: Expose `data-inline` attribute on Content part to enable distinct styling for inline date pickers
versus popover date pickers.
- **Menu**: Fix issue where `onCheckedChange` could be called twice on checkbox or radio item
- **Radio Group**: Fixed issue where arrow key navigation doesn't apply `data-focus-visible` on the newly focused item.
- **TagsInput**: Export `InputValueChangeDetails` type
### Changed
- **Async List**: Improve type inference for descriptors
- **Framework Components**: Improve runtime performance of components
## [5.3.3] - 2025-08-01
### Fixed
- **Carousel**: Fix issue where controlled carousel ignores last slide
## [5.3.2] - 2025-07-26
### Fixed
- **Dialog**
- Sync content `--layer-index` with positioner and backdrop
- Decouple `trapFocus` from `modal` so it's possible to set `modal=false` and `trapFocus=true`
## [5.3.1] - 2025-07-23
### Fixed
- **Date Picker**: Fixed issue where hovered range was connect to selected values, when it shouldn't
- **Tree View**: Fixed issue where tree view doesn't scroll into view when content overflows.
- **Portal**: Fix issue in SvelteKit where `Portal` component doesn't work as expected.
## [5.3.0] - 2025-07-22
### Added
- **Collection**: Add `useListSelection` function for managing collection item selection with support for
single/multiple selection modes
```js
const collection = createListCollection({ items: ['React', 'Vue', 'Angular'] })
const selection = useListSelection({ collection })
// Check if item is selected
const isSelected = selection.isSelected('Svelte')
// Select/deselect items
selection.select('Svelte')
selection.toggle('Angular')
```
- **File Upload**: Add support for `bind:acceptedFiles` and `defaultAcceptedFiles` to programmatically control the
accepted files
- **Signature Pad**: Add support for `bind:paths` and `defaultPaths` to programmatically control the paths
- **Date Picker**: Added hover range preview support for date picker range selection. Added `inHoveredRange`,
`firstInHoveredRange`, and `lastInHoveredRange` properties to `DayTableCellState` with corresponding data attributes
`data-in-hover-range`, `data-hover-range-start`, and `data-hover-range-end`.
Hover range states are only active when not overlapping with actual selected range, enabling distinct styling for
hover preview vs actual selection in range mode.
### Fixed
- **Date Picker**: Fix date comparison issues when time components are involved. This resolves critical issues with date
comparison operations when different date types (`CalendarDate`, `CalendarDateTime`, `ZonedDateTime`) are mixed,
particularly in scenarios involving time components.
## [5.2.0] - 2025-07-18
### Added
- **Checkbox**: Add `CheckboxGroupProvider` component for external checkbox group state management
### Fixed
- **Carousel**: Fix issue where full page carousel could trap scrolling
- **ListCollection**: Export `UseListCollectionReturn` type
- **TreeCollection**: Fix issue where the `filter` method completely deletes the children key from the node when there
are no matching children
- **Number Input**: Fix issue where default pattern does not allow negative numbers with decimal point
- **File Upload**
- Export `FileError`, `FileMimeType`, and `FileRejection` types
- Fix issue where calling `api.setFiles` invokes validation with incorrect `acceptedFiles`
- Fix issue where the browser might not be able to infer the mime type of a file due to limitations, drag source or
security restrictions. As a fallback in the file validation logic, we now infer the mime type from the file
extension.
- **Portal**: Fix issue where `lifecycle_double_unmount` warning could be triggered.
## [5.1.1] - 2025-07-05
### Fixed
- **Combobox**
- Expose `reason` to `onOpenChange` and `onInputValueChange` callbacks
- Expose `api.clearHighlightedValue` function to clear highlighted value
- **Date Picker**
- Fix issue where datepicker errors when setting `selectionMode=range` and `minView=year`
- Fix issue where `focusedValue` could not be fully controlled
- **Listbox**: Select highlighted item only if it exists in the collection
- **Progress**: Improve `valueAsString` formatting
- **Select**
- Select highlighted item only if it exists in the collection
- Expose `api.clearHighlightedValue` function to clear highlighted value
- **Tour**: Fix an issue where the `goto` function in `StepActionMap` doesn't work when passing step IDs (string)
- **Tree View**: Expose `id` in the tree node state
## [5.1.0] - 2025-07-01
### Added
- **Angle Slider [New]**: Add support for angle slider component for angle selection.
- **Color Picker**: Add support for `inline` prop to render color picker inline
- **Date Picker**: Add support for `inline` prop to render the date calendar inline
### Fixed
- **Color Picker**: Auto-prefix Hex values with `#` if missing when using the `hex` channel input
- **Menu**: Fix interaction outside detection for focusable context trigger
- **Tree View**: Improve support for rendering tree items as links
## [5.0.5] - 2025-06-28
### Fixed
- Fix issue where `bind:ref` doesn't work with components, making it impossible to access the underlying DOM element.
Now, you can pass `bind:ref` to all components.
```svelte
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]
## [5.24.0] - 2025-09-11
### Added
- **Dismissable**: Add support for layer types in dismissable layer stack. Layers can now be categorized as `dialog`,
`popover`, `menu`, or `listbox`. This enables:
- `data-nested` attribute on nested layers of the same type
- `data-has-nested` attribute on parent layers with nested children of the same type
- `--nested-layer-count` CSS variable indicating the number of nested layers of the same type
### Fixed
- **Menu**: Fix issue where hovering a partially visible item with pointer causes it to scroll into view
- **Tabs**: Fix issue where `ids` for `item` and `content` could not be customized
- **Toast**: Allow creating a toast store without any arguments
## [5.23.0] - 2025-09-08
### Added
- **Field**: Add `data-required` attribute to `Field.Label`
- **Select, Combobox, Listbox, TreeView**: Export `RootComponent` and `RootProviderComponent` types which are useful
when building compositions that wrap the `Root` and `RootProvider` components and you still want type-safety for the
collection.
```tsx
import { Select } from '@ark-ui/solid/select'
import { styled } from 'styling-lib'
const Root = styled(Select.Root) as Select.RootComponent<{}>
```
### Fixed
- **Menu**: Fix `Menu.ItemText` not working inside `Menu.TriggerItem`
## [5.22.0] - 2025-08-28
### Added
- **Combobox**: Add `ComboboxEmpty` component to display content when the combobox has no items
- **Listbox**: Add `ListboxEmpty` component to display content when the listbox has no items
- **Hover Card**: Add support for `disabled` prop
### Fixed
- **Collection**: Fix issue where disabled items could be reached via typeahead
- **Color Picker**: Fix issue where color picker was not working correctly in RTL mode
- **Date Picker**: Fix issue where datepicker doesn't revert to a valid value when the input value exceeds the min/max
and blurred
- **Dismissable**: Expose `onRequestDismiss` custom event handler for event a parent layer requests the child layer to
dismiss. If prevented via `event.preventDefault()`, the child layer will not dismiss when the parent layer is
dismissed.
- **Number Input**
- Omit the input `pattern` when `formatOptions` is provided. This prevents native pattern validation from conflicting
with formatted values (e.g., currency or percent).
- Handle empty values consistently across all format options.
- Add `data-scrubbing` attribute to the number input parts.
- **Tags Input**: Fix issue where highlighted item doesn't clear when tabbing out of the input to an external button
within the `control` part.
- **Tooltip**
- Set `closeOnPointerdown` to `false` when `closeOnClick` is set to `false`
- Reduce bundle size by replacing `@zag-js/store` dependency with a lightweight store implementation.
## [5.21.0] - 2025-08-24
### Added
- **Hooks**: Add `useAsyncList` and `useCollator` hooks for managing asynchronous list operations and locale-aware
string comparison
- **Toast**: Export type definitions `ToastActionOptions`, `ToastPlacement`, `ToastPromiseOptions`, `ToastStatus`,
`ToastStatusChangeDetails`, and `ToastType`
### Changed
- **Fieldset**:
- Update Legend component to render as `div` instead of `legend` element for improved styling flexibility
- Add `aria-labelledby` attribute to fieldset root for better accessibility by linking to legend
### Fixed
- **Date Picker**
- Clear hovered range state after completing range selection instead of waiting for pointer to leave the calendar
area.
- Fix issue where month and year select labels don't update correctly when using `min`/`max` constraints.
- Expose `disabled` on `api.getMonths()` and `api.getYears()` results to indicate options out of range for current
constraints.
- **Listbox**
- Fix issue where first enabled item should be highlighted by default when listbox receives focus and no item is
currently highlighted.
- Add `getElement` to `scrollToIndexFn` details
- Track collection changes and clear `highlightedValue` if the item is no longer in the collection.
- **ScrollArea**
- Avoid detecting hover state from portalled descendants.
- Add `data-dragging` attribute to scroll area parts.
- **Select**: Add `getElement` to `scrollToIndexFn` details
- **Combobox**: Add `getElement` to `scrollToIndexFn` details
## [5.20.0] - 2025-08-20
### Added
- **Highlight Word**: Add `exactMatch` option that enables whole-word matching using regex word boundaries.
### Fixed
- **Menu**: Fix context menu repositioning logic
- **Scroll Area**: Add `data-hover` to scroll area
## [5.19.0] - 2025-08-18
### Added
- **ScrollArea [NEW]**: Add support for new scroll area component.
### Fixed
- **ListCollection**
- Avoid recomputing groups on every call to `at()` and `indexOf()`
- Fixed bug in `find()` method (was checking `!= null` instead of `!== -1`)
- **GridCollection**: Avoid recomputing rows on every call to `getRows()`
- **Menu**
- Add `data-state` attribute for context menu trigger
- Fix context menu positioning bug where reopening at the same coordinates fails to reposition
- **ClientOnly**: Fixed issue where `ClientOnly` component was not exported correctly.
## [5.18.4] - 2025-08-14
### Fixed
- **Listbox**: Add support for navigating grid collections
- **Carousel**:
- Fix an issue where the carousel would not update when `slideCount` or `autoplay` props change.
- Fix an issue where `loop: false` was ignored when using autoplay. Now, the carousel will stop when it gets to the
last slide.
- **Date Picker**: Expose `data-inline` attribute on Content part to enable distinct styling for inline date pickers
versus popover date pickers.
- **Menu**: Fix issue where `onCheckedChange` could be called twice on checkbox or radio item
- **Radio Group**: Fixed issue where arrow key navigation doesn't apply `data-focus-visible` on the newly focused item.
- **TagsInput**: Export `InputValueChangeDetails` type
### Changed
- **Async List**: Improve type inference for descriptors
- **Framework Components**: Improve runtime performance of components
## [5.18.3] - 2025-08-01
### Fixed
- **General**: Fix issue where presence closing animation doesn't work as expected
- **Carousel**: Fix issue where controlled carousel ignores last slide
## [5.18.2] - 2025-07-26
### Fixed
- **Dialog**
- Sync content `--layer-index` with positioner and backdrop
- Decouple `trapFocus` from `modal` so it's possible to set `modal=false` and `trapFocus=true`
## [5.18.1] - 2025-07-23
### Fixed
- **Date Picker**: Fixed issue where hovered range was connect to selected values, when it shouldn't
- **Tree View**: Fixed issue where tree view doesn't scroll into view when content overflows.
## [5.18.0] - 2025-07-22
### Added
- **Collection**: Add `useListSelection` hook for managing collection item selection with support for single/multiple
selection modes
```jsx
const collection = createListCollection({ items: ['React', 'Vue', 'Angular'] })
const selection = useListSelection({ collection })
// Check if item is selected
const isSelected = selection.isSelected('React')
// Select/deselect items
selection.select('React')
selection.toggle('Vue')
```
- **File Upload**: Add support for programmatically controlling the accepted files via `acceptedFiles` and
`defaultAcceptedFiles`
- **Signature Pad**: Add support for programmatically controlling the paths via `paths` and `defaultPaths` props.
- **Date Picker**: Added hover range preview support for date picker range selection. Added `inHoveredRange`,
`firstInHoveredRange`, and `lastInHoveredRange` properties to `DayTableCellState` with corresponding data attributes
`data-in-hover-range`, `data-hover-range-start`, and `data-hover-range-end`.
Hover range states are only active when not overlapping with actual selected range, enabling distinct styling for
hover preview vs actual selection in range mode.
### Fixed
- **Date Picker**: Fix date comparison issues when time components are involved. This resolves critical issues with date
comparison operations when different date types (`CalendarDate`, `CalendarDateTime`, `ZonedDateTime`) are mixed,
particularly in scenarios involving time components.
## [5.17.0] - 2025-07-18
### Added
- **Checkbox**: Add `CheckboxGroupProvider` component for external checkbox group state management
### Fixed
- **Carousel**: Fix issue where full page carousel could trap scrolling
- **ListCollection**: Export `UseListCollectionReturn` type
- **TreeCollection**: Fix issue where the `filter` method completely deletes the children key from the node when there
are no matching children
- **Number Input**: Fix issue where default pattern does not allow negative numbers with decimal point
- **File Upload**
- Export `FileError`, `FileMimeType`, and `FileRejection` types
- Fix issue where calling `api.setFiles` invokes validation with incorrect `acceptedFiles`
- Fix issue where the browser might not be able to infer the mime type of a file due to limitations, drag source or
security restrictions. As a fallback in the file validation logic, we now infer the mime type from the file
extension.
## [5.16.1] - 2025-07-05
### Fixed
- **Combobox**
- Expose `reason` to `onOpenChange` and `onInputValueChange` callbacks
- Expose `api.clearHighlightedValue` function to clear highlighted value
- **Date Picker**
- Fix issue where datepicker errors when setting `selectionMode=range` and `minView=year`
- Fix issue where `focusedValue` could not be fully controlled
- **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 = () => (