# OVERVIEW --- # Introduction ## Motivation Most popular UI component libraries are designed to work with a specific JavaScript framework. Building UI components that work across different JavaScript frameworks presents significant challenges for organizations working with diverse technology stacks. ## Solution Ark UI provides components for building complex, interactive, and accessible user interfaces across multiple JavaScript frameworks. To achieve this, Ark UI is built on top of [Zag.js](https://zagjs.com), a UI component library powered by Finite State Machines. Check out the architecture diagram below for a high-level overview. # Getting Started ## Quickstart Running tight on schedule? No worries! Check out our quickstart examples to get started with Ark UI in seconds. - [Next.js Template](https://stackblitz.com/edit/github-qcm2dskf) - [Solid Start Template](https://stackblitz.com/edit/github-1hgkbbln) - [Nuxt Template](https://stackblitz.com/edit/github-s3sg6syq) ## Setup Guide Before you start, ensure you have a proper project setup. If not, follow your preferred application framework setup guide and then return to this guide. Install the Ark UI dependency using your preferred package manager. ```bash npm install @ark-ui/svelte // or pnpm install @ark-ui/svelte // or yarn add @ark-ui/svelte // or bun add @ark-ui/svelte ``` In this guide, we will be adding a Slider component. Copy the following code to your project. ```tsx Example not found``` Ark UI is a headless component library that doesn't include default styles. You can leverage the `data-scope` and `data-part` attributes to style your components with custom CSS. For example, to style a slider component, you can target its parts using these attributes: ```css /* Targets the */ [data-scope='slider'][data-part='root'] { display: flex; flex-direction: column; } ``` Check out the [Styling Components guide](/react/docs/guides/styling) to learn more about styling components in Ark UI. Congratulations! You've successfully set up and styled your components using Ark UI. If you run into any issues or have questions, open an issue on our [GitHub](https://github.com/chakra-ui/ark/issues/new/choose) or reach out on [Discord](https://discord.gg/ww6HE5xaZ2). Happy hacking! ✌️ # Changelog ## [Unreleased] ## [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/react/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.0] - 2025-03-17 ### Added - Added support for a cleanup function in `ref`. ### 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.0.1] - 2025-03-11 ### Fixed - Effects now flush synchronously instead of using a microtask. - **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.0] - 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 React’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. ![Performance comparison showing Ark v5 is 1.5x-4x faster than other libraries](./v5.svg) ### 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() expect(screen.getByRole('dialog')).toBeInTheDocument() }) // After it('should open by default', async () => { render() 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 `
      ` or `
        `. - **Textarea**: Fixed `ResizeObserver` warning. - **Timer**: Fixed stopping issue when switching tabs; resolved issue where `action` prop was passed to `ActionTrigger`. - **Toast**: Fixed keyboard navigation skipping close button. - **Toggle Group**: Fixed `data-focus` not being removed on blur. # Changelog ## [Unreleased] ## [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/solid/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/solid/docs/components/splitter) documentation for more details. ### Fixed - **Presence**: Fixed issue where `onExitComplete` was not being called. - **Select**: Fixed issue where select `valueAsString` lost reactivity. - **Toast**: - Fixed issue where setting `offsets` to `undefined` caused the machine to throw. - Fixed issue where `onExitComplete` was not being called. ## [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 accordionProps = createMemo(() => ({ multiple: true, value: value(), onValueChange: (e) => setValue(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.0] - 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 Solid'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(() => ) expect(screen.getByRole('dialog')).toBeInTheDocument() }) // After it('should open by default', async () => { render(() => ) 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 `
      1. ` elements correctly within `
          ` or `
            `. - **Textarea**: Fixed `ResizeObserver` warning. - **Timer**: Fixed stopping issue when switching tabs; resolved issue where `action` prop was passed to `ActionTrigger`. - **Toast**: Fixed keyboard navigation skipping close button. - **Toggle Group**: Fixed `data-focus` not being removed on blur. # Changelog ## [Unreleased] ### Changed - Replaced custom ID generator with `$props.id()` rune. ## [0.3.0] - 2025-01-08 - Added `Format` component. - Added `Progress` component. ## [0.2.0] - 2024-12-12 ## Added - Added `Ark` factory component for `asChild` prop. - Added `Environment` component. - Added `Collection` helpers. - Added `Timer` component. - Added `Highlight` component. - Added `QrCode` component. ## [0.1.0] - 2024-11-27 ### Added - Added `Avatar` component. ## [0.0.0] - 2024-11-27 # Changelog ## [Unreleased] ## [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/react/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 `
          1. ` elements correctly within `
              ` or `
                `. - **Textarea**: Fixed `ResizeObserver` warning. - **Timer**: Fixed stopping issue when switching tabs; resolved issue where `action` prop was passed to `ActionTrigger`. - **Toast**: Fixed keyboard navigation skipping close button. - **Toggle Group**: Fixed `data-focus` not being removed on blur. # About ## Acknowledgments We are committed to open source and the power of collaboration. Our work has been inspired by numerous projects and individuals who continually drive us to innovate and improve. - [Zag.js](https://zagjs.com/) - The foundation of this project - [Park UI](https://park-ui.com) - For providing the styled component demos featured in this project - [Radix Vue](https://www.radix-vue.com/) - For `useForwardPropsEmits`, which we re-export to build closed Vue components ## License This project is licensed under the terms of the [MIT license](https://github.com/chakra-ui/ark/blob/main/LICENSE). # LLMs.txt ## What is LLMs.txt? We support [LLMs.txt](https://llmstxt.org/) files for making the Ark UI documentation available to large language models (LLMs). This feature helps AI tools better understand our component library, its APIs, and usage patterns. ## Available Routes We provide several LLMs.txt routes to help AI tools access our documentation: - [llms.txt](https://ark-ui.com/llms.txt) - Contains a structured overview of all components and their documentation links - [llms-full.txt](https://ark-ui.com/llms-full.txt) - Provides comprehensive documentation including implementation details and examples - [llms-react.txt](https://ark-ui.com/llms-react.txt) - React-specific documentation and implementation details - [llms-solid.txt](https://ark-ui.com/llms-solid.txt) - SolidJS-specific documentation and implementation details - [llms-vue.txt](https://ark-ui.com/llms-vue.txt) - Vue-specific documentation and implementation details - [llms-svelte.txt](https://ark-ui.com/llms-svelte.txt) - Svelte-specific documentation and implementation details ## Usage with AI Tools ### Cursor Use the `@Docs` feature in Cursor to include the LLMs.txt files in your project. This helps Cursor provide more accurate code suggestions and documentation for Ark UI components. [Read more about @Docs in Cursor](https://docs.cursor.com/context/@-symbols/@-docs) ### Windstatic Reference the LLMs.txt files using `@` or in your `.windsurfrules` files to enhance Windstatic's understanding of Ark UI components. [Read more about Windstatic Memories](https://docs.codeium.com/windsurf/memories#memories-and-rules) ### Other AI Tools Any AI tool that supports LLMs.txt can use these routes to better understand Ark UI. Simply point your tool to any of the routes above based on your framework of choice. # GUIDES --- # Animation Adding animation to Ark UI Components is as straightforward as with any other component, but keep in mind some considerations when working with exit animations with JavaScript animation libraries. ## Animating with CSS The most straightforward method to animate your elements is using CSS. You can animate both the mounting and unmounting phases with CSS. The latter is achievable because Ark UI Components postpones the unmounting while your animation runs. Below is a simple example of creating a fade-in and fade-out animation using CSS keyframes: ```css @keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } } @keyframes fadeOut { from { opacity: 1; } to { opacity: 0; } } ``` You can use these keyframes to animate any element during its lifecycle. For instance, to apply the `fadeIn` animation when your `Tooltip` enters the 'open' state, and `fadeOut` when it enters the 'closed' state, you could use the following styles: ```css [data-scope='tooltip'][data-part='content'][data-state='open'] { animation: fadeIn 300ms ease-out; } [data-scope='tooltip'][data-part='content'][data-state='closed'] { animation: fadeOut 300ms ease-in; } ``` ## Animating with JS Libraries There's plenty of versatility when it comes to animating your Ark UI Elements with JavaScript libraries. Various libraries such as GreenSock, anime.js, Framer Motion, and more can add a new level of interaction and feedback to your UI components. One significant advantage of using Ark UI Elements is the control you have over the unmounting phase of your components. This is primarily facilitated through the `present` prop. The `present` prop allows the component to stay mounted even after its enclosing condition has been falsified, allowing for exit animations to complete before the component is removed from the DOM. # Closed Components ## Motivation Writing a few lines of code every time you need a simple `Avatar` is tedious. Creating a dedicated component encapsulates logic, simplifies the API, ensures consistent usage, and maintains clean code. This approach enhances reusability, making the component easier to maintain and test. Here's an example of an `Avatar` component that can be used consistently across your application: ```tsx Example not found``` ## Usage To use the `Avatar` component, pass the `name` and `src` props as shown below: ```jsx ``` # Collection Collections are used to manage a collection of some kind, like menus, select, combobox, etc. They provide functionalities such as sorting, searching, getting next or previous items, converting items to values or strings, checking if an item is disabled, and more. ## List Collection A list collection is a collection that is based on an array of items. It is created by passing an array of items to the constructor. ```ts import { createListCollection } from '@ark-ui/react/collection' const collection = createListCollection({ items: [ { label: 'Apple', value: 'apple' }, { label: 'Banana', value: 'banana' }, ], }) console.log(collection.items) // [{ label: 'Apple', value: 'apple' }, { label: 'Banana', value: 'banana' }] ``` ### Converting value to item Use the `find` or `findMany` method to convert a value to an item. ```ts const item = collection.find('banana') console.log(item) // { label: "Banana", value: "banana" } const items = collection.findMany(['apple', 'banana']) console.log(items) // [{ label: "Apple", value: "apple" }, { label: "Banana", value: "banana" }] ``` ### Value Traversal Use the `getNextValue` or `getPreviousValue` method to get the next or previous item based on a value. ```ts const nextValue = collection.getNextValue('apple') console.log(nextValue) // banana const previousItem = collection.getPreviousValue('banana') console.log(previousItem) // apple ``` Likewise, use the `firstValue` or `lastValue` computed properties to get the first or last item. ```ts console.log(collection.firstValue) // apple console.log(collection.lastValue) // banana ``` ### Check for value existence Use the `has` method to check if a value exists in the collection. ```ts const hasValue = collection.has('apple') console.log(hasValue) // true ``` ### Working with custom objects If you are working with custom objects, you can pass a function to the `itemToString` and `itemToValue` options to specify how to convert an item to a string and a value, respectively. > By default, we look for the `label` and `value` properties in the item. ```ts import { createListCollection } from '@ark-ui/react/collection' const collection = createListCollection({ items: [ { id: 1, name: 'apple' }, { id: 2, name: 'banana' }, { id: 3, name: 'cherry' }, ], itemToString: (item) => item.name, itemToValue: (item) => item.id, }) ``` To mark an item as disabled, pass a function to the `isItemDisabled` option. > By default, we look for the `disabled` property in the item. ```ts import { createListCollection } from '@ark-ui/react/collection' const collection = createListCollection({ items: [ { id: 1, name: 'apple' }, { id: 2, name: 'banana' }, { id: 3, name: 'cherry' }, ], isItemDisabled: (item) => item.id === 2, }) ``` ### Reorder items Use the `reorder` method to reorder items by passing the starting index and the ending index of the item to be moved. ```ts const fromIndex = 1 // Banana const toIndex = 0 // Apple collection.reorder(fromIndex, toIndex) console.log(collection.items) // [{ label: "Banana", value: "banana" }, { label: "Apple", value: "apple" }] ``` # Component State ## Context Components Context components expose state and functions to child components. In this example, `Avatar.Fallback` renders based on `loaded` state. ```tsx Example not found``` > **Good to know (RSC)**: Due to the usage of render prop, you might need to add the `'use client'` directive at the top > of your file when using React Server Components. ## Provider Components Provider components can help coordinate state and behavior between multiple components, enabling interactions that aren't possible with `Context` components alone. ```tsx Example not found``` See more in [Examples](/react/examples/popover-selection). # Composition ## The asChild Prop In Ark UI, the `asChild` prop lets you integrate custom components, ensuring consistent styling and behavior while promoting flexibility and reusability. All Ark components that render a DOM element accept the `asChild` prop. Here's an example using `asChild` to integrate a custom `Button` component within a `Popover`: ```tsx Example not found``` In this example, the `asChild` prop allows the `Button` to be used as the trigger for the `Popover`, inheriting its behaviors from Popover.Trigger. ## The Ark Factory You can use the `ark` factory to create your own elements that work just like Ark UI components. ```tsx Example not found``` This will produce the following HTML: ```html Ark UI ``` ## Limitations When using the `asChild` prop, ensure you pass only a single child element. Passing multiple children may cause rendering issues. Certain components, such as `Checkbox.Root` or `RadioGroup.Item`, have specific requirements for their child elements. For instance, they may require a label element as a child. If you change the underlying element type, ensure it remains accessible and functional. # 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. ## Styling with Panda CSS [Panda CSS](https://panda-css.com) is a build-time CSS-in-JS framework that integrates seamlessly with Ark UI, providing an efficient styling solution. ### Styling a part Panda offers various ways to write styles, but in the context of Ark UI, we recommend using the `defineSlotRecipe` function to style a component with its different parts and variants. ```ts import { accordionAnatomy } from '@ark-ui/anatomy' import { defineSlotRecipe } from '@pandacss/dev' export const accordionStyles = defineSlotRecipe({ className: 'accordion', slots: accordionAnatomy.keys(), base: { item: { borderBottom: '1px solid #e5e5e5', }, }, defaultVariants: {}, variants: {}, }) ``` ### Styling a state To style a component based on its state, you can use built in [conditions](https://panda-css.com/docs/customization/conditions) in Panda CSS. ```ts import { accordionAnatomy } from '@ark-ui/anatomy' import { defineSlotRecipe } from '@pandacss/dev' export const accordionStyles = defineSlotRecipe({ className: 'accordion', slots: accordionAnatomy.keys(), base: { item: { borderBottom: '1px solid {colors.gray.300}', _open: { // [!code highlight] backgroundColor: 'gray.100', }, }, }, defaultVariants: {}, variants: {}, }) ``` ## Styling with Tailwind CSS [Tailwind CSS](https://tailwindcss.com/) is a utility-first CSS framework providing a flexible way to style your components. ### Styling a Part To style a part, apply classes directly to the parts using either `class` or `className`, depending on the JavaScript framework. ```jsx {/* … */} ``` ### Styling a State Leverage Tailwind CSS's variant selector to style a component based on its data-state attribute. ```jsx {/* … */} ``` # 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. ```tsx Example not found``` ### Collapsible Use the `collapsible` prop to allow the user to collapse all panels. ```tsx Example not found``` ### Multiple Panels Use the `multiple` prop to allow multiple panels to be expanded simultaneously. ```tsx Example not found``` ### Horizontal Orientation By default, the Accordion is oriented vertically. Use the `orientation` prop to switch to a horizontal layout. ```tsx Example not found``` ### Animate Content Size Use the `--height` and/or `--width` CSS variables to animate the size of the content when it expands or closes: ```css @keyframes slideDown { from { opacity: 0.01; height: 0; } to { opacity: 1; height: var(--height); } } @keyframes slideUp { from { opacity: 1; height: var(--height); } to { opacity: 0.01; height: 0; } } [data-scope='accordion'][data-part='item-content'][data-state='open'] { animation: slideDown 250ms ease-in-out; } [data-scope='accordion'][data-part='item-content'][data-state='closed'] { animation: slideUp 200ms ease-in-out; } ``` ### Using the Root Provider The `RootProvider` component provides a context for the accordion. It accepts the value of the `useAccordion` hook. You can leverage it to access the component state and methods from outside the accordion. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ### Accessing the focused item Use the `focusedValue` property to get the value of the focused accordion item. ```tsx Example not found``` ### Accessing the selected items Use the `value` property to get the selected accordion items. ```tsx Example not found``` ### Setting the selected items Use the `setValue` method to set the selected accordion items. ```tsx Example not found``` ### Accessing an item's state Use the `getItemState` method to get the state of an accordion item. ```tsx Example not found``` ## API Reference ## 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. # 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: ```tsx Example not found``` ### Handling Events `Avatar` allows you to listen for loading state changes. ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the avatar. It accepts the value of the `useAvatar` hook. You can leverage it to access the component state and methods from outside the avatar. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ### Next.js Image Here's an example of how to use the `Image` component from `next/image`. ```tsx import { Avatar, useAvatarContext } from '@ark-ui/react/avatar' import Image, { ImageProps } from 'next/image' const AvatarNextImage = (props: ImageProps) => { const avatar = useAvatarContext() const { hidden, ...imageProps } = avatar.getImageProps() as ImageProps return ( ) } const Demo = () => { return ( JD ) } ``` > Refer to this [Github Discussion](https://github.com/chakra-ui/ark/discussions/3147) for more information. ## API Reference # 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: ```tsx Example not found``` ### Controlled Carousel To create a controlled Carousel component, you can manage the state of the carousel using the `index` prop and update it when the `onIndexChange` event handler is called: ```tsx Example not found``` ### 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. ```tsx Example not found``` ### Using the Root Provider The `RootProvider` sets up carousel context using the `useCarousel` hook, enabling external access to its state and methods. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference ## 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: ```tsx Example not found``` ### Controlled Checkbox To create a controlled Checkbox component, manage the state of the checked status using the `checked` prop and update it when the `onCheckedChange` event handler is called: ```tsx Example not found``` ### Indeterminate Checkbox In some cases, you may need a checkbox to represent a state that is neither checked nor unchecked, known as the indeterminate state. This can be achieved by setting the `checked` prop to `indeterminate`: ```tsx Example not found``` ### Checkbox Group Ark provides a `Checkbox.Group` component to manage a group of checkboxes. The `Checkbox.Group` component manages the state of the checkboxes and provides a way to access the checked values: ```tsx Example not found``` ### Render Prop Usage For cases where you need more flexibility in rendering, the Checkbox component offers the use of a render prop. The render prop function gives you access to the checkbox's API, allowing you to customize the checkbox control's rendering: ```tsx Example not found``` ### Using the Field Component The `Field` component helps manage form-related state and accessibility attributes of a checkbox. It includes handling ARIA labels, helper text, and error text to ensure proper accessibility. ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the checkbox. It accepts the value of the `useCheckbox` hook. You can leverage it to access the component state and methods from outside the checkbox. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference ## 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: ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the clipboard. It accepts the value of the `useClipboard` hook. You can leverage it to access the component state and methods from outside the clipboard. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference # 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: ```tsx Example not found``` ### Events You can listen for the `onExitComplete` event to know when the `Collapsible.Content` is no longer visible: ```tsx Example not found``` ### Lazy Mount To delay the mounting of the `Collapsible.Content`, use the `lazyMount` prop: ```tsx Example not found``` ### Unmount on Exit To remove the `Collapsible.Content` from the DOM when it is not visible, use the `unmountOnExit` prop: ```tsx Example not found``` ### Combining Lazy Mount and Unmount on Exit Both `lazyMount` and `unmountOnExit` can be combined to ensure that the component is mounted only when the `Collapsible` is expanded and unmounted when it is collapsed: ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the collapsible. It accepts the value of the `useCollapsible` hook. You can leverage it to access the component state and methods from outside the collapsible. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference ## Accessibility ### Keyboard Support **`Space`** Description: Opens/closes the collapsible. **`Enter`** Description: Opens/closes the collapsible. # Color Picker ## Anatomy To set up the color picker correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples Learn how to use the `ColorPicker` component in your project. Let's take a look at the most basic example ```tsx Example not found``` ### Controlled Color Picker To create a controlled Color Picker component, manage the state of the current color using the `value` prop and update it when the `onValueChange` or `onValueChangeEnd` event handler is called: ```tsx Example not found``` ### Using the Field Component The `Field` component helps manage form-related state and accessibility attributes of a color picker. It includes handling ARIA labels, helper text, and error text to ensure proper accessibility. ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the color-picker. It accepts the value of the `useColor-picker` hook. You can leverage it to access the component state and methods from outside the color-picker. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference ## 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 ```tsx Example not found``` ### Advanced Customization Extended example that shows usage with complex item objects, including disabled state for certain options. ```tsx Example not found``` ### Using the Field Component The `Field` component helps manage form-related state and accessibility attributes of a combobox. It includes handling ARIA labels, helper text, and error text to ensure proper accessibility. ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the combobox. It accepts the value of the `useCombobox` hook. You can leverage it to access the component state and methods from outside the combobox. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference ## Accessibility Complies with the [Combobox WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/). ### Keyboard Support **`ArrowDown`** Description: When the combobox is closed, opens the listbox and highlights to the first option. When the combobox is open, moves focus to the next option. **`ArrowUp`** Description: When the combobox is closed, opens the listbox and highlights to the last option. When the combobox is open, moves focus to the previous option. **`Home`** Description: When the combobox is open, moves focus to the first option. **`End`** Description: When the combobox is open, moves focus to the last option. **`Escape`** Description: Closes the listbox. **`Enter`** Description: Selects the highlighted option and closes the combobox. **`Esc`** Description: Closes the combobox # Date Picker ## Anatomy To set up the date picker correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples Learn how to use the `DatePicker` component in your project. Let's take a look at the most basic example ```tsx Example not found``` ### Range Selection To create a Date Picker that allows a range selection, set the `selectionMode` prop to `range`. ```tsx Example not found``` ### Standalone Date Picker In some cases, you might want to display a non-dismissible date picker. This can be achieved by setting the `open` prop to `true` and `closeOnSelect` prop to `false`. > Important to note that standalone date picker doesn't use the `Portal`, `Positioner` and `Content` components. ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the date-picker. It accepts the value of the `useDate-picker` hook. You can leverage it to access the component state and methods from outside the date-picker. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference ## 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 ```tsx Example not found``` ### Controlled Dialog To create a controlled Dialog component, manage the state of the dialog using the `open` and `onOpenChange` props: ```tsx Example not found``` ### Lazy Mounting Lazy mounting is a feature that allows the content of a dialog to be rendered only when the dialog is first opened. This is useful for performance optimization, especially when dialog content is large or complex. To enable lazy mounting, use the `lazyMount` prop on the `Dialog.Root` component. In addition, the `unmountOnExit` prop can be used in conjunction with `lazyMount` to unmount the dialog content when the Dialog is closed, freeing up resources. The next time the dialog is activated, its content will be re-rendered. ```tsx Example not found``` ### Using Render Function The Dialog component supports the use of a render function as a child for more control. This allows access to dialog states like `isOpen`: ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the dialog. It accepts the value of the `useDialog` hook. You can leverage it to access the component state and methods from outside the dialog. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference ## 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: ```tsx Example not found``` ### Using custom controls In some cases, you might need to use custom controls to toggle the edit and read mode. We use the render prop pattern to provide access to the internal state of the component. ```tsx Example not found``` ### Auto-resizing the editable To auto-grow the editable as the content changes, set the `autoResize` prop to `true`. ```tsx {/*...*/} ``` ### Setting a maxWidth It is a common pattern to set a maximum of the editable as it auto-grows. To achieve this, set the `maxWidth` prop to the desired value. ```tsx {/*...*/} ``` ### Editing with double click 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 {/*...*/} ``` ### Using the Field Component 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. ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the editable. It accepts the value of the `useEditable` hook. You can leverage it to access the component state and methods from outside the editable. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference ## 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. ```tsx Example not found``` ### Textarea This example illustrates how to use the `Field` component with a textarea element. ```tsx Example not found``` ### Textarea Autoresize Pass the `autoresize` prop to the `Textarea` component to enable automatic resizing as the user types. ```tsx Example not found``` ### Select This example demonstrates how to integrate the `Field` component with a select dropdown. ```tsx Example not found``` ### Using Ark Components This example demonstrates how to integrate the `Field` and `Checkbox` components. For more examples of using the `Field` component with various Ark UI elements, refer to their respective documentation. ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the field. It accepts the value of the `useField` hook. You can leverage it to access the component state and methods from outside the field. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference # Fieldset ## Examples The `Fieldset` component provides contexts such as `invalid` and `disabled` for form elements. While most Ark UI components natively support these contexts, you can also use the `Field` component with standard HTML form elements. ### Basic Usage Learn how to use the `Fieldset` component in your project. Let's take a look at the most basic example: ```tsx Example not found``` ### Fieldset with Fields This example demonstrates how to use the `Field` component with a standard input field within a `Fieldset`. ```tsx Example not found``` ### Fieldset with other Form Elements This example shows how to use the `Fieldset` component with other Ark UI form elements like `Checkbox`. ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the fieldset. It accepts the value of the `useFieldset` hook. You can leverage it to access the component state and methods from outside the fieldset. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference # File Upload ## Anatomy To set up the file upload 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 `FileUpload` component in your project. Let's take a look at the most basic example: ```tsx Example not found``` ### Using the Field Component The `Field` component helps manage form-related state and accessibility attributes of an file upload. It includes handling ARIA labels, helper text, and error text to ensure proper accessibility. ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the file-upload. It accepts the value of the `useFile-upload` hook. You can leverage it to access the component state and methods from outside the file-upload. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference # 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: ```tsx Example not found``` ### Controlled HoverCard The controlled `HoverCard` component provides an interface for managing the state of the hover card using the `open` and `onOpenChange` props: ```tsx Example not found``` ### Custom Positioning The `HoverCard` component can be customized in its placement and distance from the trigger element through the `positioning` prop: ```tsx Example not found``` ### Render Prop Usage The `HoverCard` component can also accept a render prop, giving the user more control over rendering behavior. This is useful for dynamically updating the trigger based on the state of the `HoverCard`: ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the hover-card. It accepts the value of the `useHover-card` hook. You can leverage it to access the component state and methods from outside the hover-card. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference # Menu ## Anatomy To set up the menu correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples Learn how to use the `Menu` component in your project. Let's take a look at the most basic example: ```tsx Example not found``` ### Listening to item selection Pass the `onSelect` prop to the Menu component to perform some custom logic when an item is selected. The callback is invoked with the `id` of the item. ```tsx Example not found``` ### Grouping menu items When the number of menu items gets much, it might be useful to group related menu items. To achieve this, render the `Menu.ItemGroup` component around the `Menu.Item` components. The `Menu.ItemGroupLabel` component can be used to add a label to the group. ```tsx Example not found``` ### Separating menu items To separate menu items, render the `Menu.Separator` component. ```tsx Example not found``` ### Context menu To show the menu when a trigger element is right-clicked, use the `Menu.ContextTrigger` component. Context menus are also opened during a long-press of roughly `700ms` when the pointer is pen or touch. ```tsx Example not found``` ### Nested menu To show a nested menu, render another `Menu` component and use the `Menu.TriggerItem` component to open the submenu. ```tsx Example not found``` ### Checkbox To add a checkbox to a menu item, use the `Menu.Checkbox` component. ```tsx Example not found``` ### Radio Group To group radio option items, use the `Menu.RadioGroup` component. ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the menu. It accepts the value of the `useMenu` hook. You can leverage it to access the component state and methods from outside the menu. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference ## Accessibility Complies with the [Menu WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/). ### Keyboard Support **`Space`** Description: Activates/Selects the highlighted item **`Enter`** Description: Activates/Selects the highlighted item **`ArrowDown`** Description: Highlights the next item in the menu **`ArrowUp`** Description: Highlights the previous item in the menu **`ArrowRight + ArrowLeft`** Description: When focus is on trigger, opens or closes the submenu depending on reading direction. **`Esc`** Description: Closes the menu and moves focus to the trigger # Number Input ## Anatomy To set up the number input correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples Learn how to use the `NumberInput` component in your project. Let's take a look at the most basic example: ```tsx Example not found``` ### Setting a minimum and maximum value Pass the `min` prop or `max` prop to set an upper and lower limit for the input. By default, the input will restrict the value to stay within the specified range. ```tsx Example not found``` ### Adjusting the precision of the value In some cases, you might need the value to be rounded to specific decimal points. Set the `formatOptions` and provide `Intl.NumberFormatOptions` such as `maximumFractionDigits` or `minimumFractionDigits`. ```tsx Example not found``` ### Scrubbing the input value The NumberInput supports the scrubber interaction pattern. To use this pattern, render the `NumberInput.Scrubber` component. It uses the Pointer lock API and tracks the pointer movement. It also renders a virtual cursor which mimics the real cursor's pointer. ```tsx Example not found``` ### Using the mouse wheel to change value The NumberInput exposes a way to increment/decrement the value using the mouse wheel event. To activate this, set the `allowMouseWheel` prop to `true`. ```tsx Example not found``` ### Clamp value when user blurs the input In most cases, users can type custom values in the input field. If the typed value is greater than the max, the value is reset to max when the user blur out of the input. To disable this behavior, pass `clampValueOnBlur` and set to `false`. ```tsx Example not found``` ### Usage within forms To use the number input within forms, set the `name` prop. ```tsx Example not found``` ### Format and parse value To apply custom formatting to the input's value, set the `formatOptions` and provide `Intl.NumberFormatOptions` such as `style` and `currency`. ```tsx Example not found``` ### Using the Field Component The `Field` component helps manage form-related state and accessibility attributes of a number input. It includes handling ARIA labels, helper text, and error text to ensure proper accessibility. ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the number-input. It accepts the value of the `useNumber-input` hook. You can leverage it to access the component state and methods from outside the number-input. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference ## 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: ```tsx Example not found``` ### Controlled Pagination To create a controlled Pagination component, manage the state of the current page using the `page` prop and update it when the `onPageChange` event handler is called: ```tsx Example not found``` ### Customizing Pagination You can customize the Pagination component by setting various props such as `dir`, `pageSize`, `siblingCount`, and `translations`. Here's an example of a customized Pagination: ```tsx Example not found``` ### Using the 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. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference # 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: ```tsx Example not found``` ### Setting a default value To set the initial value of the pin input, set the `defaultValue` prop. ```tsx Example not found``` ### Changing the placeholder To customize the default pin input placeholder `β—‹` for each input, pass the placeholder prop and set it to your desired value. ```tsx Example not found``` ### Blur on complete By default, the last input maintains focus when filled, and we invoke the `onValueComplete` callback. To blur the last input when the user completes the input, set the prop `blurOnComplete` to `true`. ```tsx Example not found``` ### Using OTP mode To trigger smartphone OTP auto-suggestion, it is recommended to set the `autocomplete` attribute to "one-time-code". The pin input component provides support for this automatically when you set the `otp` prop to true. ```tsx Example not found``` ### Securing the text input When collecting private or sensitive information using the pin input, you might need to mask the value entered, similar to ``. Pass the `mask` prop to `true`. ```tsx Example not found``` ### Listening for changes The pin input component invokes several callback functions when the user enters: - `onValueChange` β€” Callback invoked when the value is changed. - `onValueComplete` β€” Callback invoked when all fields have been completed (by typing or pasting). - `onValueInvalid` β€” Callback invoked when an invalid value is entered into the input. An invalid value is any value that doesn't match the specified "type". ### Using the Field Component The `Field` component helps manage form-related state and accessibility attributes of a pin input. It includes handling ARIA labels, helper text, and error text to ensure proper accessibility. ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the pin-input. It accepts the value of the `usePin-input` hook. You can leverage it to access the component state and methods from outside the pin-input. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference ## 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: ```tsx Example not found``` ### Using a Portal By default, the popover is rendered in the same DOM hierarchy as the trigger. To render the popover within a portal, set the `portalled` prop to `true`. > Note: This requires that you render the component within a `Portal` based on the framework you use. ```tsx Example not found``` ### Adding an arrow To render an arrow within the popover, render the component `Popover.Arrow` and `Popover.ArrowTip` as children of `Popover.Positioner`. ```tsx Example not found``` ### Listening for open and close events When the popover is opened or closed, we invoke the `onOpenChange` callback. ```tsx Example not found``` ### Control the open state Use the `isOpen` prop to control the open state of the popover. ```tsx Example not found``` ### Modifying the close behavior The popover is designed to close on blur and when the esc key is pressed. To prevent it from closing on blur (clicking or focusing outside), pass the `closeOnInteractOutside` prop and set it to `false`. To prevent it from closing when the esc key is pressed, pass the `closeOnEsc` prop and set it to `false`. ```tsx Example not found``` ### Changing the placement To change the placement of the popover, set the `positioning` prop. ```tsx Example not found``` ### Changing the modality In some cases, you might want the popover to be modal. This means that it'll: - trap focus within its content - block scrolling on the body - disable pointer interactions outside the popover - hide content behind the popover from screen readers To make the popover modal, set the `modal` prop to `true`. When `modal={true}`, we set the `portalled` attribute to `true` as well. ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the popover. It accepts the value of the `usePopover` hook. You can leverage it to access the component state and methods from outside the popover. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference ## 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: ```tsx Example not found``` ### Set a min and max value By default, the maximum is `100`. If that's not what you want, you can easily specify a different bound by changing the value of the `max` prop. You can do the same with the minimum value by setting the `min` prop. For example, to show the user a progress from `10` to `30`, you can use: ```tsx Example not found``` ### Indeterminate value The progress component is determinate by default, with the value and max set to 50 and 100 respectively. To render an indeterminate progress, you will have to set the `value` to `null`. ```tsx Example not found``` ### Showing a value text Progress bars can only be interpreted by sighted users. To include a text description to support assistive technologies like screen readers, use the `value` part in `translations`. ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the progress. It accepts the value of the `useProgress` hook. You can leverage it to access the component state and methods from outside the progress. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference ## 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: ```tsx Example not found``` ### Set a min and max value By default, the maximum is `100`. If that's not what you want, you can easily specify a different bound by changing the value of the `max` prop. You can do the same with the minimum value by setting the `min` prop. For example, to show the user a progress from `10` to `30`, you can use: ```tsx Example not found``` ### Indeterminate progress The progress component is determinate by default, with the value and max set to 50 and 100 respectively. To render an indeterminate progress, you will have to set the `value` to `null`. ```tsx Example not found``` ### Showing a value text Progress bars can only be interpreted by sighted users. To include a text description to support assistive technologies like screen readers, use the `value` part in `translations`. ```tsx Example not found``` ### Changing the orientation By default, the progress is assumed to be horizontal. To change the orientation to vertical, set the orientation property in the machine's context to vertical. > Don't forget to change the styles of the vertical progress by specifying its height ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the progress. It accepts the value of the `useProgress` hook. You can leverage it to access the component state and methods from outside the progress. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference ## 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: ```tsx Example not found``` ### Download a QR Code You can download the QR code by using the `QrCode.DownloadTrigger`. You will have to provide the `fileName` and the `mimeType` of the image. ```tsx 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. ```tsx Example not found``` ### Error Correction In cases where the link is too long or the logo overlay covers a significant area, the error correction level can be increased. Use the `encoding.ecc` or `encoding.boostEcc` property to set the error correction level: - `L`: Allows recovery of up to 7% data loss (default) - `M`: Allows recovery of up to 15% data loss - `Q`: Allows recovery of up to 25% data loss - `H`: Allows recovery of up to 30% data loss ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the QR code. It accepts the value of the `useQrCode` hook. You can leverage it to access the component state and methods from outside the QR code. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference # Radio Group ## Anatomy To set up the radio group correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ### Design impact on the asChild property The `RadioGroup.Item` element of the radio group is a `label` element. This is because the radio group is a form control and should be associated with a label to provide context and meaning to the user. Otherwise, the HTML and accessibility structure will be invalid. > If you need to use the `asChild` property, make sure that the `label` element is the direct child of the > `RadioGroup.Item` component. ## Examples Learn how to use the `RadioGroup` component in your project. Let's take a look at the most basic example: ```tsx Example not found``` ### Disabling the radio group To make a radio group disabled, set the `disabled` prop to `true`. ```tsx Example not found``` ### Setting the initial value To set the radio group's initial value, set the `defaultValue` prop to the value of the radio item to be selected by default. ```tsx Example not found``` ### Listening for changes When the radio group value changes, the `onValueChange` callback is invoked. ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the radio-group. It accepts the value of the `useRadio-group` hook. You can leverage it to access the component state and methods from outside the radio-group. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference ## 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: ```tsx Example not found``` ### Using half ratings Allow `0.5` value steps by setting the `allowHalf` prop to `true`. Ensure to render the correct icon if the `isHalf` value is set in the Rating components render callback. ```tsx Example not found``` ### Using a default value ```tsx Example not found``` ### Controlled When using the `RatingGroup` component, you can use the `value` and `onValueChange` props to control the state. ```tsx Example not found``` ### Disabling the rating group To make the rating group disabled, set the `disabled` prop to `true`. ```tsx Example not found``` ### Readonly rating group To make the rating group readonly, set the `readOnly` prop to `true`. ```tsx Example not found``` ### Usage within forms To use the rating group within forms, pass the prop `name`. It will render a hidden input and ensure the value changes get propagated to the form correctly. ```tsx Example not found``` ### Using the Field Component The `Field` component helps manage form-related state and accessibility attributes of a rating group. It includes handling ARIA labels, helper text, and error text to ensure proper accessibility. ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the rating-group. It accepts the value of the `useRating-group` hook. You can leverage it to access the component state and methods from outside the rating-group. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference ## Accessibility ### Keyboard Support **`ArrowRight`** Description: Moves focus to the next star, increasing the rating value based on the `allowHalf` property. **`ArrowLeft`** Description: Moves focus to the previous star, decreasing the rating value based on the `allowHalf` property. **`Enter`** Description: Selects the focused star in the rating group. # Segment Group ## Anatomy To set up the segmented control correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples Learn how to use the `SegmentGroup` component in your project. Let's take a look at the most basic example: ```tsx Example not found``` ### Initial Value To set a default segment on initial render, use the `defaultValue` prop: ```tsx Example not found``` ### Controlled Segment Group To create a controlled SegmentGroup component, manage the current selected segment using the `value` prop and update it when the `onValueChange` event handler is called: ```tsx Example not found``` ### Disabled Segment To disable a segment, simply pass the `disabled` prop to the `SegmentGroup.Item` component: ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the radio-group. It accepts the value of the `useRadio-group` hook. You can leverage it to access the component state and methods from outside the radio-group. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference ## 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: ```tsx Example not found``` ### Advanced Customization For advanced customizations and item properties like `disabled`: ```tsx Example not found``` ### Multiple Selection To enable `multiple` item selection: ```tsx Example not found``` ### Controlled Component For scenarios where you want to control the Select component's state: ```tsx Example not found``` ### Usage with a Form Library See how to use the Select component with popular form libraries: ```tsx Example not found``` ### Using the Field Component The `Field` component helps manage form-related state and accessibility attributes of a select. It includes handling ARIA labels, helper text, and error text to ensure proper accessibility. ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the select. It accepts the value of the `useSelect` hook. You can leverage it to access the component state and methods from outside the select. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference ## Accessibility Complies with the [Listbox WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/). ### Keyboard Support **`Space`** Description: When focus is on trigger, opens the select and focuses the first selected item.
                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: ```tsx Example not found``` ### Image Preview After the user draws a signature, you can display a preview of the signature as an image. This is useful when you want to show the user a preview of the signature before saving it. ```tsx Example not found``` ### 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. ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the signature-pad. It accepts the value of the `useSignature-pad` hook. You can leverage it to access the component state and methods from outside the signature-pad. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference # 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: ```tsx Example not found``` ### Range Slider You can add multiple thumbs to the slider by adding multiple `Slider.Thumb` ```tsx Example not found``` ### Adding marks You can add marks to the slider track by using the `Slider.MarkerGroup` and `Slider.Marker` components. Position the `Slider.Marker` components relative to the track by providing the `value` prop. ```tsx Example not found``` ### Setting the initial value To set the slider's initial value, set the `defaultValue` prop to the array of numbers. ```tsx Example not found``` ### Specifying the minimum and maximum By default, the minimum is `0` and the maximum is `100`. If that's not what you want, you can easily specify different bounds by changing the values of the `min` and/or `max` props. For example, to ask the user for a value between `-10` and `10`, you can use: ```tsx Example not found``` ### Setting the value's granularity By default, the granularity, is `1`, meaning that the value is always an integer. You can change the step attribute to control the granularity. For example, If you need a value between `5` and `10`, accurate to two decimal places, you should set the value of step to `0.01`: ```tsx Example not found``` ### Listening for changes When the slider value changes, the `onValueChange` and `onValueChangeEnd` callbacks are invoked. You can use this to set up custom behaviors in your app. ```tsx Example not found``` ### Changing the orientation By default, the slider is assumed to be horizontal. To change the orientation to vertical, set the orientation property in the machine's context to vertical. In this mode, the slider will use the arrow up and down keys to increment/decrement its value. > Don't forget to change the styles of the vertical slider by specifying its height ```tsx Example not found``` ### Changing the origin By default, the slider's origin is at the start of the track. To change the origin to the center of the track, set the `origin` prop to `center`. ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the slider. It accepts the value of the `useSlider` hook. You can leverage it to access the component state and methods from outside the slider. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference ## 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: ```tsx Example not found``` ### Using Render Props The Splitter component allows you to pass a function as a child to gain direct access to its API. This provides more control and allows you to modify the size of the panels programmatically: ```tsx Example not found``` ### Handling Events Splitter also provides `onResizeStart`, `onResize`, and `onResizeEnd` events which can be useful to perform some actions during the start and end of the resizing process: ```tsx Example not found``` ### Vertical Splitter By default, the Splitter component is horizontal. If you need a vertical splitter, use the `orientation` prop: ```tsx Example not found``` ### Collapsible Panels To make a panel collapsible, set the `collapsible` prop to `true` on the panel you want to make collapsible. Additionally, you can use the `collapsedSize` prop to set the size of the panel when it's collapsed. > This can be useful for building sidebar layouts. ```tsx Example not found``` ### Multiple Panels Here's an example of how to use the `Splitter` component with multiple panels. ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the splitter. It accepts the value of the `useSplitter` hook. You can leverage it to access the component state and methods from outside the splitter. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference ## 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. ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the steps. It accepts the value of the `useSteps` hook. You can leverage it to access the component state and methods from outside the steps. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference # 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: ```tsx Example not found``` ### Controlled Switch For a controlled Switch component, the state of the toggle is managed using the checked prop, and updates when the `onCheckedChange` event handler is called: ```tsx Example not found``` ### Render Prop Usage The Switch component also allows for a render prop, granting direct access to its internal state. This enables you to dynamically adjust and customize aspects of the component based on its current state: ```tsx Example not found``` ### Using the Field Component The `Field` component helps manage form-related state and accessibility attributes of a switch. It includes handling ARIA labels, helper text, and error text to ensure proper accessibility. ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the switch. It accepts the value of the `useSwitch` hook. You can leverage it to access the component state and methods from outside the switch. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference ## 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: ```tsx Example not found``` ### Initial Tab To set a default tab on initial render, use the `defaultValue` prop: ```tsx Example not found``` ### Tab Indicator To provide a visual cue for the selected tab, use the `Tabs.Indicator` component: ```tsx Example not found``` ### Lazy Mounting Lazy mounting is a feature that allows the content of a tab to be rendered only when the tab is first activated. This is useful for performance optimization, especially when tab content is large or complex. To enable lazy mounting, use the `lazyMount` prop on the `Tabs.Content` component. In addition, the `unmountOnExit` prop can be used in conjunction with `lazyMount` to unmount the tab content when the tab is deactivated, freeing up resources. The next time the tab is activated, its content will be re-rendered. ```tsx Example not found``` ### Disabled Tab To disable a tab, simply pass the `disabled` prop to the `Tabs.Trigger` component: ```tsx Example not found``` ### Controlled Tabs To create a controlled Tabs component, manage the current selected tab using the `value` prop and update it when the `onValueChange` event handler is called: ```tsx Example not found``` ### Router Controlled Tabs When using frameworks like Next.js, Remix, or React Router, controlling the active tabs based on the URL can be useful. To achieve this, you need to do two things: - Set the `value` prop to the current URL path. - Listen to the `onValueChange` event and update the URL path. Here's an example using Remix Router ```tsx import { Tabs } from '@ark-ui/react/tabs' import { useLocation, useNavigate, Link } from '@remix-run/react' export default function App() { const { pathname } = useLocation() const navigate = useNavigate() const lastPathFragment = pathname.substring(pathname.lastIndexOf('/') + 1) const activeTab = lastPathFragment.length > 0 ? lastPathFragment : 'homepage' return ( { navigate(`/${value === 'home' ? '' : value}`) }} > Home Page 1 Page 2 ) } ``` ### Vertical Tabs The default orientation of the tabs is `horizontal`. To change the orientation, set the `orientation` prop to `vertical`. ```tsx Example not found``` ### Manual Activation By default, the tab can be selected when it receives focus from either the keyboard or pointer interaction. This is called automatic tab activation. In contrast, manual tab activation means the tab is selected with the Enter key or by clicking on the tab. ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the tabs. It accepts the value of the `useTabs` hook. You can leverage it to access the component state and methods from outside the tabs. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference ## 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: ```tsx Example not found``` ### Navigating and Editing tags When the input has an empty value or the caret is at the start position, the tags can be selected by using the arrow left and arrow right keys. When "visual" focus in on any tag: - Pressing Enter or double-clicking on the tag will put it in edit mode, allowing the user change its value and press Enter to commit the changes. - Pressing Delete or Backspace will delete the tag that has _visual_ focus. ### Setting the initial tags To set the initial tag values, set the `defaultValue` prop. ```tsx Example not found``` ### Limiting the number of tags To limit the number of tags within the component, you can set the `max` property to the limit you want. The default value is `Infinity`. When the tag reaches the limit, new tags cannot be added except the `allowOverflow` prop is set to `true`. ```tsx Example not found``` ### Validating Tags Before a tag is added, the `validate` function is called to determine whether to accept or reject a tag. A common use-case for validating tags is preventing duplicates or validating the data type. ```tsx Example not found``` ### Blur behavior When the tags input is blurred, you can configure the action the component should take by passing the `blurBehavior` prop. - `add` β€” Adds the tag to the list of tags. - `clear` β€” Clears the tags input value. ```tsx Example not found``` ### Paste behavior To add a tag when a arbitrary value is pasted in the input element, pass the `addOnPaste` prop. When a value is pasted, the component will: - check if the value is a valid tag based on the `validate` option - split the value by the `delimiter` option passed ```tsx Example not found``` ### Disable tag editing by default the tags can be edited by double-clicking on the tag or focusing on them and pressing Enter. To disable this behavior, pass `editable={false}` ```tsx Example not found``` ### Events During the lifetime of the tags input interaction, here's a list of events we emit: - `onValueChange` β€” invoked when the tag value changes. - `onHighlightChange` β€” invoked when a tag has visual focus. - `onValueInvalid` β€” invoked when the max tag count is reached or the `validate` function returns `false`. ```tsx Example not found``` ### Using the Field Component The `Field` component helps manage form-related state and accessibility attributes of a tags input. It includes handling ARIA labels, helper text, and error text to ensure proper accessibility. ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the tags-input. It accepts the value of the `useTags-input` hook. You can leverage it to access the component state and methods from outside the tags-input. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference ## 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: ```tsx Example not found``` ### Countdown Timer You can create a countdown timer by setting the `targetMs` prop to a future timestamp: ```tsx Example not found``` ### Timer Events The Timer component provides events that you can listen to for various timer-related actions. - The `onComplete` event is triggered when the timer reaches its target time. - The `onTick` event is called on each timer update, providing details about the current timer state. ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the timer. It accepts the value of the `useTimer` hook. You can leverage it to access the component state and methods from outside the timer. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference # 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. ```tsx Example not found``` ### Update Toast To update a toast, use the `toast.update` method. ```tsx Example not found``` ### Action To add an action to a toast, use the `toast.action` property. ```tsx Example not found``` ## API Reference # 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: ```tsx Example not found``` ### Multiple Selection Demonstrates how to enable `multiple` selection within the group. ```tsx Example not found``` ### Initial Value Shows how to set an initial value in the toggle group. ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the toggle-group. It accepts the value of the `useToggle-group` hook. You can leverage it to access the component state and methods from outside the toggle-group. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference ## 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: ```tsx Example not found``` ### Controlled Use the `pressed` and `onPressedChange` props to control the toggle's state. ```tsx Example not found``` ### Disabled Use the `disabled` prop to disable the toggle. ```tsx Example not found``` ### Indicator Use the `Toggle.Indicator` component to render different indicators based on the state of the toggle. ```tsx Example not found``` ## API Reference # Tooltip ## Anatomy To set up the tooltip 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 `Tooltip` component in your project. Let's take a look at the most basic example: ```tsx Example not found``` ### Controlled Tooltip To create a controlled Tooltip component, manage the state of whether the tooltip is open using the `open` prop: ```tsx Example not found``` ### Using a Render Function For more control over the Tooltip's functionality, you can use a function as a child, which provides access to the Tooltip API: ```tsx Example not found``` ### Adding an Arrow To display an arrow pointing to the trigger from the tooltip, use the `Tooltip.Arrow` and `Tooltip.ArrowTip` components: ```tsx Example not found``` ### Configuring Delay Timings To configure the delay timings for the Tooltip, use the `closeDelay` and `openDelay` props: ```tsx Example not found``` ### Custom Positioning To customize the position of the Tooltip relative to the trigger, use the `positioning` prop: ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the tooltip. It accepts the value of the `useTooltip` hook. You can leverage it to access the component state and methods from outside the tooltip. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference ## 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 # 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: ```tsx Example not found``` ### Using the Root Provider The `RootProvider` component provides a context for the tree-view. It accepts the value of the `useTree-view` hook. You can leverage it to access the component state and methods from outside the tree-view. ```tsx Example not found``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ## API Reference ## Accessibility Complies with the [Tree View WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/). ### Keyboard Support **`Tab`** Description: Moves focus to the tree view, placing the first tree view item in focus. **`Enter + Space`** Description: Selects the item or branch node **`ArrowDown`** Description: Moves focus to the next node **`ArrowUp`** Description: Moves focus to the previous node **`ArrowRight`** Description: When focus is on a closed branch node, opens the branch.
                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 --- # Download Trigger ## Motivation The `DownloadTrigger` component provides a convenient way to programmatically trigger file downloads in web applications. It handles the complexities of downloading files, whether they are URLs, Blobs, or other data types. ## Examples ### Basic Pass the data you want to download to the `data` prop, and specify the `fileName` and `mimeType` of the file. ```tsx Example not found``` ### Download SVG Here's an example of how to download an SVG file. ```tsx Example not found``` ### Promise You can also trigger downloads from a promise that returns a `Blob`, `File`, or `string`. ```tsx Example not found``` ## 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. ```tsx Example not found``` ### 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 }) => {/* Your App */}} ) ``` ### 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 ( portalNode?.shadowRoot ?? document}>{/* Your App */} ) } ``` ## Context Use the `useEnvironmentContext` hook to access the `RootNode`, `Document`, and `Window`. ```tsx Example not found``` ## API Reference # 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 ```tsx Example not found``` ### Autofocus The focus trap respects elements with the `autofocus` attribute. ```tsx Example not found``` ### Initial Focus Use the `initialFocus` prop to set the element that should receive initial focus when the trap is activated. ```tsx Example not found``` ## API Reference # Format Byte ## Usage The byte formatting component extends the number formatting capabilities to handle byte-specific formatting, including automatic unit conversion and display options. ```jsx import { Format } from '@ark-ui/react' ``` ## Examples ### Basic Use the `Format.Byte` component to format a byte value with default options. ```tsx Example not found``` ### Sizes Use the `sizes` prop to specify custom byte sizes for formatting. ```tsx Example not found``` ### Locale Use the `locale` prop to format the byte value according to a specific locale. ```tsx Example not found``` ### Unit Use the `unit` prop to specify the unit of the byte value. ```tsx Example not found``` ### Unit Display Use the `unitDisplay` prop to specify the display of the unit. ```tsx Example not found``` # Format Number ## Usage The number formatting logic is handled by the native `Intl.NumberFormat` 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.Number` component to format a number with default options. ```tsx Example not found``` ### Percentage Use the `style="percent"` prop to format the number as a percentage. ```tsx Example not found``` ### Currency Use the `style="currency"` prop along with the `currency` prop to format the number as a currency. ```tsx Example not found``` ### Locale Use the `locale` prop to format the number according to a specific locale. ```tsx Example not found``` ### Unit Use the `style="unit"` prop along with the `unit` prop to format the number with a specific unit. ```tsx Example not found``` ### Compact Notation Use the `notation="compact"` prop to format the number in compact notation. ```tsx Example not found``` # Frame ## Usage The `Frame` component is used to render a component in an iframe. - Tracks the size of the content and exposes them via css variables. - Support for `head` prop to inject scripts and styles. - Support for mount and unmount callbacks. ```jsx import { Frame } from '@ark-ui/react' ``` ## Examples ### Basic Wrap your component in the `Frame` component to render it in an iframe. ```tsx Example not found``` ### Injecting Script Using the `onMount` prop, you can inject a script into the iframe. ```tsx Example not found``` ### Custom src doc Use the `srcDoc` prop to specify the HTML content of the page to use in the iframe. ```tsx Example not found``` # 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. ```tsx Example not found``` ### Multiple Queries You can highlight multiple terms by passing an array of strings to the `query` prop. ```tsx Example not found``` ### Case Sensitivity By default, the highlighting is case-sensitive. Use the `ignoreCase` prop to make it case-insensitive. ```tsx Example not found``` ### 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`. ```tsx Example not found``` ## API Reference ## Customization The Highlight component wraps matched text in `` tags. ```tsx ``` Style the `mark` tags using CSS to customize the appearance of highlighted text. ```css .highlighted-text { background-color: yellow; } ``` # Locale ## Setup The `LocaleProvider` component sets the locale for your app, formatting dates, numbers, and other locale-specific data. > **Note:** If no `LocaleProvider` is setup, the default locale for the app will be `en-US` and therefore the direction > will be `ltr`. ```tsx Example not found``` ## Usage To access the current locale and direction settings, use the `useLocaleContext` hook. ```tsx Example not found``` ## API Reference # 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. ```tsx Example not found``` ### Lazy Mount To delay the mounting of a child component until the `present` prop is set to true, use the `lazyMount` prop: ```tsx Example not found``` ### Unmount on Exit To remove the child component from the DOM when it's not present, use the `unmountOnExit` prop: ```tsx Example not found``` ### 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: ```tsx Example not found``` ## API Reference