# OVERVIEW

---

# Getting Started 

## Quickstart

Running tight on schedule? No worries! Check out our quickstart example to get started with Ark Ripple 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

<Steps>
<Step title="Prerequisite" number="1">

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.

</Step>
<Step title="Install Ark Ripple" number="2">

Install the Ark UI dependency using your preferred package manager.

```bash
npm install ark-ripple
// or
pnpm install ark-ripple
// or
yarn add ark-ripple
// or
bun add ark-ripple
```

</Step>
<Step number="3" title="Add a component">

In this guide, we will be adding a Slider component. Copy the following code to your project.

<ExampleCode component="slider" id="basic" />

</Step>

<Step number="4" title="Style a component">
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 <Slider.Root /> */
[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 Ripple.

</Step>

<Step number="5" title="That's it">

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/anubra266/ark-ripple/issues/new) or reach out on
[Discord](https://discord.gg/3kjgmUWj).

Happy hacking! ✌️

</Step>
</Steps>


# Changelog 

## [Unreleased]

## [1.2.0] - 2025-09-04

### Added

- Added `get_component_props` tool to retrieve component props/properties for specific Ark UI components

## [1.1.2] - 2025-09-03

### Fixed

Add missing node shebang to the `stdio` script.

## [1.1.1] - 2025-09-01

### Fixed

Don't ship the `src` directory to the package.

## [1.1.0] - 2025-09-01

### Added

- Initial release of the official MCP server for Ark UI



# GUIDES

---

# Styling 

## Overview

Ark Ripple 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.

### Data Attributes

Ark Ripple 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
<div data-scope="accordion" data-part="item" data-state="open"></div>
```

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 Ripple components.

### Class Names

If you prefer using classes instead of data attributes, utilize `class` or `className` prop to add custom classes to Ark
Ripple components.

Pass a class:

```jsx
<Accordion.Root>
  <Accordion.Item className="AccordionItem">{/* … */}</Accordion.Item>
</Accordion.Root>
```

Then use in styles:

```css
.AccordionItem {
  border-bottom: 1px solid #e5e5e5;

  &[data-state='open'] {
    background-color: #f5f5f5;
  }
}
```

## 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
<Accordion.Root>
  <Accordion.Item className="border-b border-gray-300">{/* … */}</Accordion.Item>
</Accordion.Root>
```

### Styling a State

Leverage Tailwind CSS's variant selector to style a component based on its data-state attribute.

```jsx
<Accordion.Root>
  <Accordion.Item className="border-b border-gray-300 data-[state=open]:bg-gray-100">{/* … */}</Accordion.Item>
</Accordion.Root>
```


# Composition 

## The asChild Prop

In Ark Ripple, `asChild` lets you integrate custom components, ensuring consistent styling and behavior while
promoting flexibility and reusability. All Ark components that render a DOM element accept `asChild`.

Here's an example using `asChild` to integrate a custom `Button` component within a `Popover`:

<ExampleCode id="as-child" component="popover" />

In this example, `asChild` 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 Ripple components.

<ExampleCode id="factory" component="popover" />

This will produce the following HTML:

```html
<span id="child" class="parent child" style="background: red; color: blue;">Ark UI</span>
```

## ID Composition

When composing components that need to work together, share IDs between them using the `ids` prop for proper
accessibility and interaction.

```ripple
import { Avatar } from 'ark-ripple/avatar'
import { Tooltip } from 'ark-ripple/tooltip'

export component TooltipWithAvatar() {
  const id = ':ark-avatar'

  <Tooltip.Root ids={{ trigger: id }}>
    <Tooltip.Trigger>
      component asChild({ propsFn }){
        <Avatar.Root {...propsFn({ ids: { root: id } })}>
          <Avatar.Image src="https://bit.ly/sage-adebayo" />
          <Avatar.Fallback>{"SA"}</Avatar.Fallback>
        </Avatar.Root>
      }
    </Tooltip.Trigger>
    <Tooltip.Positioner>
      <Tooltip.Content>{"Abraham Aremu is online"}</Tooltip.Content>
    </Tooltip.Positioner>
  </Tooltip.Root>
}
```

Both components share the same `id` through their `ids` props, creating proper accessibility bindings, `aria-*`
attributes and interaction behavior.

## Limitations

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.


# Component State 

Need to access a component's state? You have three options:

| Approach                        | When to use it                                |
| ------------------------------- | --------------------------------------------- |
| `Component.Context`             | Quick inline access via named children        |
| `use*Context` hooks             | Build custom child components that read state |
| `useComponent` + `RootProvider` | Control the component from outside            |

## Context Components

Use `Component.Context` to access state inline via named children. Here, `Avatar.Fallback` reads the `loaded` state to
show different content:

<ExampleCode id="context" component="avatar" />

## Context Hooks

Every component exports a `use*Context` hook (like `useDialogContext` or `useMenuContext`). Call it from any child
component to access state and methods—no render props needed.

```ripple
import { Dialog, useDialogContext } from 'ark-ripple/dialog'

component CustomCloseButton() {
  const dialog = useDialogContext()
  
  <button onClick={() => dialog.setOpen(false)}>
    {"Close "} {dialog.open ? 'open' : 'closed'}
  </button>
}

export component Demo() {
  <Dialog.Root>
    <Dialog.Trigger>Open</Dialog.Trigger>
    <Dialog.Content>
      <CustomCloseButton />
    </Dialog.Content>
  </Dialog.Root>
}
```

The hook returns the same API as `Component.Context`, just without the nesting.

## Provider Components

Need to control a component from outside its tree? Use a `useComponent` hook (like `useDialog`) with `RootProvider`.

> When you use `RootProvider`, skip the `Root` component—you don't need both.

<ExampleCode id="root-provider" component="accordion" />

## Choosing the Right Approach

- **`Component.Context`** — Quick inline access for conditional rendering
- **`use*Context` hooks** — Build reusable child components that need parent state
- **`useComponent` + `RootProvider`** — Trigger actions from outside (like opening a dialog from a menu item)


# Animation 

Adding animation to Ark Ripple 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 Ripple 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 Ripple 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 Ripple 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.


# Forms 

Ark Ripple provides the `Field` and `Fieldset` components for integrating with native `form` element or any form library.

## Field Context

Form components in Ark Ripple automatically integrate with `Field` through context. When nested inside a `Field.Root`, they
inherit `disabled`, `invalid`, `required`, and `readOnly` states automatically.

```ripple
import { Field } from 'ark-ripple/field'
import { NumberInput } from 'ark-ripple/number-input'

component Demo() {
  <Field.Root disabled>
    <NumberInput.Root />  // NumberInput will be disabled
  </Field.Root>
}
```

### Accessible Labels

When building accessible forms, you need to ensure that they are properly labeled and described.

- `Field.Label`: Used to provide an accessible label the input.
- `Field.HelperText`: Used to provide additional instructions about the input.

These components are automatically linked to the input element via the `aria-describedby` attribute.

> **Best practice**: Make sure that labels are visible (and not just used as placeholders) for screen readers to read
> them.

```ripple
import { Field } from 'ark-ripple/field'

component Demo() {
  <form>
    <Field.Root>
      <Field.Label>{"Username"}</Field.Label>
      <Field.Input placeholder="Enter your username" />
      <Field.HelperText>{"This will be your public display name."}</Field.HelperText>
    </Field.Root>
  </form>
}
```

### Error Handling and Validation

When the input is invalid, you can use the `Field.ErrorText` component to provide an error message for the input, and
pass the `invalid` prop to the `Field.Root` component.

> **Best practice**: Make sure to provide clear, specific error messages that are easy to understand and fix.

```ripple
import { Field } from 'ark-ripple/field'

component Demo() {
  <form>
    <Field.Root invalid>
      <Field.Label>{"Username"}</Field.Label>
      <Field.Input placeholder="Enter your username" />
      <Field.ErrorText>{"Username is required."}</Field.ErrorText>
    </Field.Root>
  </form>
}
```

### Required Fields

To indicate that a field is required, you can pass the `required` prop to the `Field.Root` component. Optionally, you
can use the `Field.RequiredIndicator` component to indicate that the field is required.

> **Best practice**: Don't rely solely on color to indicate required status

```ripple
import { Field } from 'ark-ripple/field'

export component Demo() {
  <form>
    <Field.Root required>
      <Field.Label>
        {"Username"}
        <Field.RequiredIndicator>{"(required)"}</Field.RequiredIndicator>
      </Field.Label>
      <Field.Input placeholder="Enter your username" />
      <Field.ErrorText>{"Username is required."}</Field.ErrorText>
    </Field.Root>
  </form>
}
```

To indicate that a field is optional, use the `fallback` prop on the `Field.RequiredIndicator` component.

```ripple
<Field.RequiredIndicator fallback="Optional">{"(required)"}</Field.RequiredIndicator>
```

### Native Controls

Field supports native HTML form controls including `input`, `textarea`, and `select`:

```ripple
import { Field } from 'ark-ripple/field'

export component Demo(){
  <form>
    // Input
    <Field.Root>
      <Field.Label>{"Email"}</Field.Label>
      <Field.Input type="email" placeholder="you@example.com" />
    </Field.Root>

    // Textarea
    <Field.Root>
      <Field.Label>{"Bio"}</Field.Label>
      <Field.Textarea placeholder="Tell us about yourself" />
    </Field.Root>

    // Select
    <Field.Root>
      <Field.Label>{"Country"}</Field.Label>
      <Field.Select>
        <option value="us">{"United States"}</option>
        <option value="uk">{"United Kingdom"}</option>
        <option value="de">{"Germany"}</option>
      </Field.Select>
    </Field.Root>
  </form>
}
```

### Form Reset

When the `reset` event is triggered on a form, all Ark Ripple components automatically sync their internal state with the
form's reset values.

> **Note**: For this to work correctly, always include the `HiddenInput` component in your form controls. The hidden
> input participates in the native form reset mechanism, and Ark Ripple listens for this to sync the component state.

```ripple
import { Checkbox } from 'ark-ripple/checkbox'

component Demo() {
  <form>
    <Checkbox.Root name="terms" defaultChecked>
      <Checkbox.Label>{"I agree to the terms"}</Checkbox.Label>
      <Checkbox.Control>
        <Checkbox.Indicator />
      </Checkbox.Control>
      <Checkbox.HiddenInput />
    </Checkbox.Root>

    // Clicking reset will restore checkbox to defaultChecked state
    <button type="reset">{"Reset"}</button>
    <button type="submit">{"Submit"}</button>
  </form>
}
```

## Fieldset Context

When you have multiple fields in a form or a component that renders multiple `input` elements, you can use the
`Fieldset` component to group them together.

Common use cases checkbox group, radio group, input + select composition, etc.

### Checkbox Group

```ripple
import { Fieldset } from 'ark-ripple/fieldset'

const items = [
  { label: 'React', value: 'react' },
  { label: 'Solid', value: 'solid' },
  { label: 'Vue', value: 'vue' },
  { label: 'Svelte', value: 'svelte' },
]

component Demo() {
  <Fieldset.Root>
    <Fieldset.Legend>{"Frameworks"}</Fieldset.Legend>
    <Checkbox.Group name="framework">
      for (const item of items; key item.value) {
        <Checkbox.Root value={item.value} />
      }
    </Checkbox.Group>
    <Fieldset.HelperText>{"Choose your preferred frameworks"}</Fieldset.HelperText>
  </Fieldset.Root>
}
```

### Radio Group

```ripple
import { Fieldset } from 'ark-ripple/fieldset'
import { RadioGroup } from 'ark-ripple/radio-group'

const items = [
  { label: 'React', value: 'react' },
  { label: 'Solid', value: 'solid' },
  { label: 'Vue', value: 'vue' },
  { label: 'Svelte', value: 'svelte' },
]

component Demo() {
  <Fieldset.Root>
    <Fieldset.Legend>{"Frameworks"}</Fieldset.Legend>
    <RadioGroup.Root name="framework">
      for (const item of items; key item.value) {
        <RadioGroup.Item value={item.value} key={item.value} />
      }
    </RadioGroup.Root>
    <Fieldset.HelperText>{"Choose your preferred framework"}</Fieldset.HelperText>
  </Fieldset.Root>
}
```



# AI FOR AGENTS

---

# LLMs.txt 

## What is LLMs.txt?

We support [LLMs.txt](https://llmstxt.org/) files for making the Ark Ripple 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.rip/llms.txt) - Contains a structured overview of all components and their documentation
  links
- [llms-full.txt](https://ark-ui.rip/llms-full.txt) - Provides comprehensive documentation including implementation
  details and examples

## 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 Ripple 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 Ripple
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 Ripple. Simply point your tool to any of
the routes above based on your framework of choice.



# COLLECTIONS

---

# 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-ripple/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-ripple/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-ripple/collection'

const collection = createListCollection({
  items: [
    { id: 1, name: 'apple' },
    { id: 2, name: 'banana' },
    { id: 3, name: 'cherry' },
  ],
  isItemDisabled: (item) => item.id === 2,
})
```

### Reorder items

Use the `reorder` method to reorder items by passing the starting index and the ending index of the item to be moved.

```ts
const fromIndex = 1 // Banana
const toIndex = 0 // Apple
collection.reorder(fromIndex, toIndex)

console.log(collection.items) // [{ label: "Banana", value: "banana" }, { label: "Apple", value: "apple" }]
```


# Tree Collection 

A tree collection is designed to manage hierarchical data structures like file systems, navigation menus, or
organization charts. It provides powerful methods for traversing, manipulating, and querying tree structures.

```ts
import { createTreeCollection } from 'ark-ripple/collection'

const treeData = {
  value: 'root',
  label: 'Root',
  children: [
    {
      value: 'folder1',
      label: 'Folder 1',
      children: [
        { value: 'file1', label: 'File 1.txt' },
        { value: 'file2', label: 'File 2.txt' },
      ],
    },
    {
      value: 'folder2',
      label: 'Folder 2',
      children: [
        {
          value: 'subfolder1',
          label: 'Subfolder 1',
          children: [{ value: 'file3', label: 'File 3.txt' }],
        },
      ],
    },
  ],
}

const tree = createTreeCollection({ rootNode: treeData })
```

### Navigation Methods

The tree collection provides various methods to navigate through the hierarchical structure.

#### Getting First and Last Nodes

```ts
const firstNode = tree.getFirstNode()
console.log(firstNode?.value) // "folder1"

const lastNode = tree.getLastNode()
console.log(lastNode?.value) // "folder2"
```

#### Sequential Navigation

Navigate to the next or previous node in the tree traversal order:

```ts
const nextNode = tree.getNextNode('file1')
console.log(nextNode?.value) // "file2"

const previousNode = tree.getPreviousNode('file2')
console.log(previousNode?.value) // "file1"
```

### Hierarchical Relationships

#### Parent and Children

Get parent and descendant nodes:

```ts
// Get parent node
const parentNode = tree.getParentNode('file1')
console.log(parentNode?.value) // "folder1"

// Get all ancestor nodes
const ancestors = tree.getParentNodes('file3')
console.log(ancestors.map((n) => n.value)) // ["folder2", "subfolder1"]

// Get all descendant nodes
const descendants = tree.getDescendantNodes('folder1')
console.log(descendants.map((n) => n.value)) // ["file1", "file2"]

// Get descendant values only
const descendantValues = tree.getDescendantValues('folder2')
console.log(descendantValues) // ["subfolder1", "file3"]
```

#### Sibling Navigation

Navigate between sibling nodes:

```ts
// Assuming we have the index path of "file1"
const indexPath = tree.getIndexPath('file1') // [0, 0]

const nextSibling = tree.getNextSibling(indexPath)
console.log(nextSibling?.value) // "file2"

const previousSibling = tree.getPreviousSibling(indexPath)
console.log(previousSibling) // undefined (no previous sibling)

// Get all siblings
const siblings = tree.getSiblingNodes(indexPath)
console.log(siblings.map((n) => n.value)) // ["file1", "file2"]
```

### Index Path Operations

Work with index paths to identify node positions:

```ts
// Get index path for a value
const indexPath = tree.getIndexPath('file3')
console.log(indexPath) // [1, 0, 0]

// Get value from index path
const value = tree.getValue([1, 0, 0])
console.log(value) // "file3"

// Get full value path (all ancestors + node)
const valuePath = tree.getValuePath([1, 0, 0])
console.log(valuePath) // ["folder2", "subfolder1", "file3"]

// Get node at specific index path
const node = tree.at([1, 0])
console.log(node?.value) // "subfolder1"
```

### Tree Queries

#### Branch and Leaf Detection

```ts
// Check if a node is a branch (has children)
const folder1Node = tree.findNode('folder1')
const isBranch = tree.isBranchNode(folder1Node!)
console.log(isBranch) // true

// Get all branch values
const branchValues = tree.getBranchValues()
console.log(branchValues) // ["folder1", "folder2", "subfolder1"]
```

#### Tree Traversal

Visit all nodes with custom logic:

```ts
tree.visit({
  onEnter: (node, indexPath) => {
    console.log(`Visiting: ${node.value} at depth ${indexPath.length}`)

    // Skip certain branches
    if (node.value === 'folder2') {
      return 'skip' // Skip this branch and its children
    }
  },
})
```

#### Filtering

Create a new tree with filtered nodes:

```ts
// Keep only nodes that match criteria
const filteredTree = tree.filter((node, indexPath) => {
  return node.value.includes('file') // Only keep files
})

console.log(filteredTree.getValues()) // ["file1", "file2", "file3"]
```

### Tree Manipulation

#### Adding Nodes

```ts
const newFile = { value: 'newfile', label: 'New File.txt' }

// Insert after a specific node
const indexPath = tree.getIndexPath('file1')
const updatedTree = tree.insertAfter(indexPath!, [newFile])

// Insert before a specific node
const updatedTree2 = tree.insertBefore(indexPath!, [newFile])
```

#### Removing Nodes

```ts
const indexPath = tree.getIndexPath('file2')
const updatedTree = tree.remove([indexPath!])

console.log(updatedTree.getValues()) // file2 is removed
```

#### Moving Nodes

```ts
const fromIndexPaths = [tree.getIndexPath('file1')!]
const toIndexPath = tree.getIndexPath('folder2')!

const updatedTree = tree.move(fromIndexPaths, toIndexPath)
// file1 is now moved under folder2
```

#### Replacing Nodes

```ts
const indexPath = tree.getIndexPath('file1')!
const newNode = { value: 'replacedfile', label: 'Replaced File.txt' }

const updatedTree = tree.replace(indexPath, newNode)
```

### Utility Methods

#### Flattening

Convert the tree to a flat structure:

```ts
const flatNodes = tree.flatten()
console.log(flatNodes.map((n) => ({ value: n.value, depth: n._indexPath.length })))
// [{ value: "folder1", depth: 1 }, { value: "file1", depth: 2 }, ...]
```

#### Getting All Values

```ts
const allValues = tree.getValues()
console.log(allValues) // ["folder1", "file1", "file2", "folder2", "subfolder1", "file3"]
```

#### Depth Calculation

```ts
const depth = tree.getDepth('file3')
console.log(depth) // 3 (root -> folder2 -> subfolder1 -> file3)
```

### Working with Custom Node Types

You can customize how the tree collection interprets your data:

```ts
interface CustomNode {
  id: string
  name: string
  items?: CustomNode[]
  isDisabled?: boolean
}

const customTree = createTreeCollection<CustomNode>({
  rootNode: {
    id: 'root',
    name: 'Root',
    items: [
      { id: '1', name: 'Item 1', isDisabled: false },
      { id: '2', name: 'Item 2', isDisabled: true },
    ],
  },
  nodeToValue: (node) => node.id,
  nodeToString: (node) => node.name,
  nodeToChildren: (node) => node.items,
  isNodeDisabled: (node) => node.isDisabled ?? false,
})
```

### Creating Trees from File Paths

Create a tree structure from file paths:

```ts
import { createFileTreeCollection } from 'ark-ripple/collection'

const paths = ['src/components/Button.tsx', 'src/components/Input.tsx', 'src/utils/helpers.ts', 'docs/README.md']

const fileTree = createFileTreeCollection(paths)
console.log(fileTree.getBranchValues()) // ["src", "components", "utils", "docs"]
```

> **Good to know**: Tree collections are immutable - all modification methods return a new tree instance rather than
> modifying the original.


# Async List 

The `useAsyncList` hook manages asynchronous data operations for list collections. It provides a comprehensive solution
for loading, filtering, sorting, and paginating data with built-in loading states, error handling, and request
cancellation.

```tsx
import { useAsyncList } from 'ark-ripple/collection'

const list = useAsyncList<User>({
  async load({ signal }) {
    const response = await fetch('/api/users', { signal })
    const users = await response.json()
    return { items: users }
  },
})

console.log(list.items) // User[]
console.log(list.loading) // boolean
console.log(list.error) // Error | null
```

## Examples

### Loading Data

Load data asynchronously from an API using the `load` function and update the list when the data is ready.

**Example: async-list/reload**

```ripple
import { useAsyncList } from 'ark-ripple/collection';
import { Loader } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/async-list.module.css';

interface Quote {
  id: number;
  quote: string;
  author: string;
}

export component Reload() {
  const list = useAsyncList<Quote>(
    {
      autoReload: true,
      async load() {
        const response = await fetch(
          `https://dummyjson.com/quotes?limit=4&skip=${Math.floor(Math.random() * 50)}`,
        );

        if (!response.ok) throw new Error('Failed to fetch quotes');

        const data = await response.json();
        return { items: data.quotes };
      },
    },
  );

  <div class={styles.Root}>
    <div class={styles.Header}>
      <button
        class={button.Root}
        onClick={() => {
          @list.reload();
        }}
        disabled={@list.loading}
      >
        if (@list.loading) {
          <Loader class={styles.Spinner} />
          {'Loading'}
        } else {
          {'Reload Quotes'}
        }
      </button>
    </div>

    if (@list.error) {
      <div class={styles.Error}>
        {'Error: '}
        {@list.error.message}
      </div>
    }

    <div class={styles.ItemGroup}>
      for (const quote of @list.items; key quote.id) {
        <div class={styles.Item}>
          <div class={styles.ItemContent}>
            <div class={styles.ItemDescription}>
              {'"'}
              {quote.quote}
              {'"'}
            </div>
            <div class={styles.ItemMeta}>
              {'— '}
              {quote.author}
            </div>
          </div>
        </div>
      }
    </div>
  </div>
}

```

### Infinite Loading

Implement pagination by returning a cursor that indicates more data is available.

**Example: async-list/infinite-loading**

```ripple
import { useAsyncList } from 'ark-ripple/collection';
import { Loader } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/async-list.module.css';

const LIMIT = 4;

interface Post {
  userId: number;
  id: number;
  title: string;
  body: string;
}

export component InfiniteLoading() {
  const list = useAsyncList<Post, number>(
    {
      autoReload: true,
      async load({ cursor }: { cursor?: number }) {
        const page = cursor || 1;
        const start = (page - 1) * LIMIT;

        const response = await fetch(
          `https://jsonplaceholder.typicode.com/posts?_start=${start}&_limit=${LIMIT}`,
        );

        if (!response.ok) throw new Error('Failed to fetch posts');

        const posts: Post[] = await response.json();
        const hasNextPage = posts.length === LIMIT;

        return {
          items: posts,
          cursor: hasNextPage ? page + 1 : undefined,
        };
      },
    },
  );

  <div class={styles.Root}>
    <div class={styles.Header}>
      <span class={styles.Status}>
        {'Loaded '}
        {@list.items.length}
        {' posts'}
        {@list.cursor ? ' (more available)' : null}
      </span>
      if (@list.cursor) {
        <button
          class={button.Root}
          onClick={() => {
            @list.loadMore();
          }}
          disabled={@list.loading}
        >
          if (@list.loading) {
            <Loader class={styles.Spinner} />
            {'Loading'}
          } else {
            {'Load More'}
          }
        </button>
      }
    </div>

    if (@list.error) {
      <div class={styles.Error}>
        {'Error: '}
        {@list.error.message}
      </div>
    }

    <div class={styles.ItemGroup}>
      for (const post of @list.items; key post.id) {
        <div class={styles.Item}>
          <div class={styles.ItemContent}>
            <div class={styles.ItemTitle}>
              {@list.items.indexOf(post) + 1}
              {'. '}
              {post.title}
            </div>
            <div class={styles.ItemDescription}>{post.body}</div>
          </div>
        </div>
      }
    </div>
  </div>
}

```

### Filtering

Filter data based on user input with automatic debouncing and loading states.

**Example: async-list/filter**

```ripple
import { useAsyncList } from 'ark-ripple/collection';
import { Loader } from 'lucide-ripple';
import field from 'styles/field.module.css';
import styles from 'styles/async-list.module.css';

const LIMIT = 4;

interface User {
  id: number;
  name: string;
  email: string;
  department: string;
  role: string;
}

const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

const mockUsers: User[] = [
  {
    id: 1,
    name: 'Alice Johnson',
    email: 'alice@example.com',
    department: 'Engineering',
    role: 'Senior Developer',
  },
  {
    id: 2,
    name: 'Bob Smith',
    email: 'bob@example.com',
    department: 'Marketing',
    role: 'Marketing Manager',
  },
  {
    id: 3,
    name: 'Carol Davis',
    email: 'carol@example.com',
    department: 'Engineering',
    role: 'Frontend Developer',
  },
  {
    id: 4,
    name: 'David Wilson',
    email: 'david@example.com',
    department: 'Sales',
    role: 'Sales Representative',
  },
  {
    id: 5,
    name: 'Eva Brown',
    email: 'eva@example.com',
    department: 'Engineering',
    role: 'DevOps Engineer',
  },
  {
    id: 6,
    name: 'Frank Miller',
    email: 'frank@example.com',
    department: 'Support',
    role: 'Customer Success',
  },
  {
    id: 7,
    name: 'Grace Lee',
    email: 'grace@example.com',
    department: 'Marketing',
    role: 'Content Creator',
  },
  {
    id: 8,
    name: 'Henry Taylor',
    email: 'henry@example.com',
    department: 'Engineering',
    role: 'Backend Developer',
  },
  {
    id: 9,
    name: 'Ivy Anderson',
    email: 'ivy@example.com',
    department: 'Sales',
    role: 'Account Manager',
  },
  {
    id: 10,
    name: 'Jack Thompson',
    email: 'jack@example.com',
    department: 'Support',
    role: 'Technical Support',
  },
  {
    id: 11,
    name: 'Kate Martinez',
    email: 'kate@example.com',
    department: 'Marketing',
    role: 'Brand Manager',
  },
  {
    id: 12,
    name: 'Liam Garcia',
    email: 'liam@example.com',
    department: 'Engineering',
    role: 'Full Stack Developer',
  },
  {
    id: 13,
    name: 'Mia Rodriguez',
    email: 'mia@example.com',
    department: 'Sales',
    role: 'Sales Director',
  },
  {
    id: 14,
    name: 'Noah Lopez',
    email: 'noah@example.com',
    department: 'Support',
    role: 'Support Manager',
  },
  {
    id: 15,
    name: 'Olivia White',
    email: 'olivia@example.com',
    department: 'Engineering',
    role: 'UI Designer',
  },
  {
    id: 16,
    name: 'Paul Harris',
    email: 'paul@example.com',
    department: 'Marketing',
    role: 'Digital Marketer',
  },
  {
    id: 17,
    name: 'Quinn Clark',
    email: 'quinn@example.com',
    department: 'Engineering',
    role: 'Mobile Developer',
  },
  {
    id: 18,
    name: 'Ruby Lewis',
    email: 'ruby@example.com',
    department: 'Sales',
    role: 'Business Development',
  },
  {
    id: 19,
    name: 'Sam Young',
    email: 'sam@example.com',
    department: 'Support',
    role: 'Documentation Specialist',
  },
  {
    id: 20,
    name: 'Tina Walker',
    email: 'tina@example.com',
    department: 'Marketing',
    role: 'Social Media Manager',
  },
];

export component Filter() {
  const list = useAsyncList<User>(
    {
      initialItems: mockUsers.slice(0, LIMIT),
      async load({ filterText }: { filterText?: string }) {
        await delay(500);
        if (!filterText) return { items: mockUsers.slice(0, LIMIT) };
        const filtered = mockUsers.filter(
          (user) => user.name.toLowerCase().includes(filterText.toLowerCase()) ||
            user.email.toLowerCase().includes(filterText.toLowerCase()),
        );
        return { items: filtered.slice(0, LIMIT) };
      },
    },
  );

  <div class={styles.Root}>
    <div class={styles.Header}>
      <input
        class={field.Input}
        type="text"
        placeholder="Search users..."
        value={@list.filterText}
        onInput={(e) => {
          @list.setFilterText((e.target as HTMLInputElement).value);
        }}
      />
      if (@list.loading) {
        <span class={styles.Loading}>
          <Loader class={styles.Spinner} />
          {'Searching'}
        </span>
      }
    </div>

    if (@list.error) {
      <div class={styles.Error}>
        {'Error: '}
        {@list.error.message}
      </div>
    }

    <div class={styles.ItemGroup}>
      for (const user of @list.items; key user.id) {
        <div class={styles.Item}>
          <div class={styles.ItemContent}>
            <div class={styles.ItemTitle}>{user.name}</div>
            <div class={styles.ItemDescription}>{user.email}</div>
            <div class={styles.ItemMeta}>
              {user.department}
              {' • '}
              {user.role}
            </div>
          </div>
        </div>
      }
    </div>

    if (@list.items.length === 0 && !@list.loading) {
      <div class={styles.Empty}>{'No results found'}</div>
    }
  </div>
}

```

### Sorting (Client-side)

Sort data on the client side after loading from the server.

**Example: async-list/sort-client-side**

```ripple
import { useAsyncList } from 'ark-ripple/collection';
import { ArrowDown, ArrowUpDown, ArrowUp, Loader } from 'lucide-ripple';
import styles from 'styles/async-list.module.css';

interface User {
  id: number;
  name: string;
  username: string;
  email: string;
  phone: string;
  website: string;
}

const collator = new Intl.Collator();

const cols: { key: keyof User; label: string }[] = [
  { key: 'name', label: 'Name' },
  { key: 'username', label: 'Username' },
  { key: 'email', label: 'Email' },
];

export component SortClientSide() {
  const list = useAsyncList<User>(
    {
      autoReload: true,
      load: async () => {
        const response = await fetch('https://jsonplaceholder.typicode.com/users?_limit=5');
        const data = await response.json();
        return { items: data };
      },
      sort({ items, descriptor }) {
        return {
          items: items.sort((a, b) => {
            const { column, direction } = descriptor;
            let cmp = collator.compare(
              String(a[column as keyof User]),
              String(b[column as keyof User]),
            );
            if (direction === 'descending') {
              cmp *= -1;
            }
            return cmp;
          }),
        };
      },
    },
  );

  const handleSort = (column: keyof User) => {
    const currentSort = @list.sortDescriptor;
    let direction: 'ascending' | 'descending' = 'ascending';
    if (currentSort?.column === column && currentSort.direction === 'ascending') {
      direction = 'descending';
    }
    @list.sort({ column, direction });
  };

  <div class={styles.Root}>
    if (@list.loading) {
      <div class={styles.Loading}>
        <Loader class={styles.Spinner} />
        {'Loading'}
      </div>
    }
    if (@list.error) {
      <div class={styles.Error}>
        {'Error: '}
        {@list.error.message}
      </div>
    }
    <div class={styles.Status}>
      {'Sorted by: '}
      {@list.sortDescriptor
        ? `${@list.sortDescriptor.column} (${@list.sortDescriptor.direction})`
        : 'none'}
    </div>

    <table class={styles.Table}>
      <thead>
        <tr>
          for (const col of cols; key col.key) {
            <th onClick={() => handleSort(col.key)}>
              {col.label}
              {' '}
              if (!@list.sortDescriptor || @list.sortDescriptor.column !== col.key) {
                <ArrowUpDown />
              } else if (@list.sortDescriptor.direction === 'ascending') {
                <ArrowUp />
              } else {
                <ArrowDown />
              }
            </th>
          }
        </tr>
      </thead>
      <tbody>
        for (const user of @list.items; key user.id) {
          <tr>
            <td>{user.name}</td>
            <td>{user.username}</td>
            <td>{user.email}</td>
          </tr>
        }
      </tbody>
    </table>
  </div>
}

```

### Sorting (Server-side)

Send sort parameters to the server and reload data when sorting changes.

**Example: async-list/sort-server-side**

```ripple
import { useAsyncList } from 'ark-ripple/collection';
import { ArrowDown, ArrowUpDown, ArrowUp, Loader } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/async-list.module.css';

interface Product {
  id: number;
  title: string;
  price: number;
  description: string;
  category: string;
  image: string;
  rating: {
    rate: number;
    count: number;
  };
}

export component SortServerSide() {
  const list = useAsyncList<Product>(
    {
      autoReload: true,
      async load({ sortDescriptor }: { sortDescriptor?: { column: string; direction: string } }) {
        const url = new URL('https://fakestoreapi.com/products');
        url.searchParams.set('limit', '5');
        if (sortDescriptor) {
          const { direction } = sortDescriptor;
          url.searchParams.set('sort', direction === 'ascending' ? 'asc' : 'desc');
        }
        const response = await fetch(url);
        const items = await response.json();
        return { items };
      },
    },
  );

  const handleSort = (column: keyof Product) => {
    const currentSort = @list.sortDescriptor;
    let direction: 'ascending' | 'descending' = 'ascending';
    if (currentSort?.column === column && currentSort.direction === 'ascending') {
      direction = 'descending';
    }
    @list.sort({ column, direction });
  };

  <div class={styles.Root}>
    <div class={styles.Header}>
      <button class={button.Root} onClick={() => handleSort('title')}>
        {'Sort by title '}
        if (!@list.sortDescriptor || @list.sortDescriptor.column !== 'title') {
          <ArrowUpDown />
        } else if (@list.sortDescriptor.direction === 'ascending') {
          <ArrowUp />
        } else {
          <ArrowDown />
        }
      </button>
      if (@list.loading) {
        <span class={styles.Loading}>
          <Loader class={styles.Spinner} />
          {'Loading'}
        </span>
      }
    </div>

    if (@list.error) {
      <div class={styles.Error}>
        {'Error: '}
        {@list.error.message}
      </div>
    }

    <div class={styles.ItemGroup}>
      for (const product of @list.items; key product.id) {
        <div class={styles.Item} data-variant="outline">
          <div class={styles.ItemMedia}>
            <img src={product.image} alt={product.title} />
          </div>
          <div class={styles.ItemContent}>
            <div class={styles.ItemTitle}>{product.title}</div>
            <div class={styles.ItemDescription}>
              {'

### Dependencies

Automatically reload data when dependencies change, such as filter selections or external state.

**Example: async-list/dependencies**

```ripple
import { useAsyncList } from 'ark-ripple/collection';
import { Loader } from 'lucide-ripple';
import { track } from 'ripple';
import field from 'styles/field.module.css';
import styles from 'styles/async-list.module.css';

const LIMIT = 5;

interface User {
  id: number;
  name: string;
  email: string;
  department: string;
  role: string;
}

const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

const departments = ['Engineering', 'Marketing', 'Sales', 'Support'];

const roles = [
  'Senior Developer',
  'Marketing Manager',
  'Frontend Developer',
  'Sales Representative',
  'DevOps Engineer',
  'Customer Success',
  'Content Creator',
  'Backend Developer',
  'Account Manager',
  'Technical Support',
  'Brand Manager',
  'Full Stack Developer',
  'Sales Director',
  'Support Manager',
  'UI Designer',
  'Digital Marketer',
  'Mobile Developer',
  'Business Development',
  'Documentation Specialist',
  'Social Media Manager',
];

const mockUsers: User[] = [
  {
    id: 1,
    name: 'Alice Johnson',
    email: 'alice@example.com',
    department: 'Engineering',
    role: 'Senior Developer',
  },
  {
    id: 2,
    name: 'Bob Smith',
    email: 'bob@example.com',
    department: 'Marketing',
    role: 'Marketing Manager',
  },
  {
    id: 3,
    name: 'Carol Davis',
    email: 'carol@example.com',
    department: 'Engineering',
    role: 'Frontend Developer',
  },
  {
    id: 4,
    name: 'David Wilson',
    email: 'david@example.com',
    department: 'Sales',
    role: 'Sales Representative',
  },
  {
    id: 5,
    name: 'Eva Brown',
    email: 'eva@example.com',
    department: 'Engineering',
    role: 'DevOps Engineer',
  },
  {
    id: 6,
    name: 'Frank Miller',
    email: 'frank@example.com',
    department: 'Support',
    role: 'Customer Success',
  },
  {
    id: 7,
    name: 'Grace Lee',
    email: 'grace@example.com',
    department: 'Marketing',
    role: 'Content Creator',
  },
  {
    id: 8,
    name: 'Henry Taylor',
    email: 'henry@example.com',
    department: 'Engineering',
    role: 'Backend Developer',
  },
  {
    id: 9,
    name: 'Ivy Anderson',
    email: 'ivy@example.com',
    department: 'Sales',
    role: 'Account Manager',
  },
  {
    id: 10,
    name: 'Jack Thompson',
    email: 'jack@example.com',
    department: 'Support',
    role: 'Technical Support',
  },
  {
    id: 11,
    name: 'Kate Martinez',
    email: 'kate@example.com',
    department: 'Marketing',
    role: 'Brand Manager',
  },
  {
    id: 12,
    name: 'Liam Garcia',
    email: 'liam@example.com',
    department: 'Engineering',
    role: 'Full Stack Developer',
  },
  {
    id: 13,
    name: 'Mia Rodriguez',
    email: 'mia@example.com',
    department: 'Sales',
    role: 'Sales Director',
  },
  {
    id: 14,
    name: 'Noah Lopez',
    email: 'noah@example.com',
    department: 'Support',
    role: 'Support Manager',
  },
  {
    id: 15,
    name: 'Olivia White',
    email: 'olivia@example.com',
    department: 'Engineering',
    role: 'UI Designer',
  },
  {
    id: 16,
    name: 'Paul Harris',
    email: 'paul@example.com',
    department: 'Marketing',
    role: 'Digital Marketer',
  },
  {
    id: 17,
    name: 'Quinn Clark',
    email: 'quinn@example.com',
    department: 'Engineering',
    role: 'Mobile Developer',
  },
  {
    id: 18,
    name: 'Ruby Lewis',
    email: 'ruby@example.com',
    department: 'Sales',
    role: 'Business Development',
  },
  {
    id: 19,
    name: 'Sam Young',
    email: 'sam@example.com',
    department: 'Support',
    role: 'Documentation Specialist',
  },
  {
    id: 20,
    name: 'Tina Walker',
    email: 'tina@example.com',
    department: 'Marketing',
    role: 'Social Media Manager',
  },
];

export component Dependencies() {
  let selectedDepartment = track('');
  let selectedRole = track('');

  const dependencies = track(() => [@selectedDepartment, @selectedRole]);

  const list = useAsyncList<User>(
    {
      initialItems: mockUsers.slice(0, LIMIT),
      dependencies,
      async load({ filterText }: { filterText?: string }) {
        await delay(400);

        let items = mockUsers;

        if (@selectedDepartment) {
          items = items.filter((user) => user.department === @selectedDepartment);
        }

        if (@selectedRole) {
          items = items.filter((user) => user.role === @selectedRole);
        }

        if (filterText) {
          items = items.filter(
            (user) => user.name.toLowerCase().includes(filterText.toLowerCase()) ||
              user.email.toLowerCase().includes(filterText.toLowerCase()),
          );
        }

        return { items: items.slice(0, LIMIT) };
      },
    },
  );

  <div class={styles.Root}>
    <div class={styles.Header}>
      <select
        class={field.Select}
        value={@selectedDepartment}
        onChange={(e) => {
          @selectedDepartment = (e.target as HTMLSelectElement).value;
        }}
      >
        <option value="">{'All Departments'}</option>
        for (const dept of departments; key dept) {
          <option value={dept}>{dept}</option>
        }
      </select>

      <select
        class={field.Select}
        value={@selectedRole}
        onChange={(e) => {
          @selectedRole = (e.target as HTMLSelectElement).value;
        }}
      >
        <option value="">{'All Roles'}</option>
        for (const role of roles; key role) {
          <option value={role}>{role}</option>
        }
      </select>

      <input
        class={field.Input}
        type="text"
        placeholder="Search..."
        value={@list.filterText}
        onInput={(e) => {
          @list.setFilterText((e.target as HTMLInputElement).value);
        }}
      />

      if (@list.loading) {
        <span class={styles.Loading}>
          <Loader class={styles.Spinner} />
          {'Loading'}
        </span>
      }
    </div>

    if (@list.error) {
      <div class={styles.Error}>
        {'Error: '}
        {@list.error.message}
      </div>
    }

    <div class={styles.Status}>
      {'Found '}
      {@list.items.length}
      {' users'}
    </div>

    <div class={styles.ItemGroup}>
      for (const user of @list.items; key user.id) {
        <div class={styles.Item}>
          <div class={styles.ItemContent}>
            <div class={styles.ItemTitle}>{user.name}</div>
            <div class={styles.ItemDescription}>{user.email}</div>
            <div class={styles.ItemMeta}>
              {user.department}
              {' • '}
              {user.role}
            </div>
          </div>
        </div>
      }
    </div>

    if (@list.items.length === 0 && !@list.loading) {
      <div class={styles.Empty}>{'No users found with current filters'}</div>
    }
  </div>
}

```

## API Reference

### Props

- **load** (`(params: LoadParams<C>) => Promise<LoadResult<T, C>>`) - Function to load data asynchronously
- **sort** (`(params: SortParams<T>) => Promise<SortResult<T>> | SortResult<T>`) - Optional function for client-side
  sorting
- **autoReload** (`boolean`, default: `false`) - Whether to automatically reload data on mount
- **initialItems** (`T[]`, default: `[]`) - Initial items to display before first load
- **dependencies** (`any[]`, default: `[]`) - Values that trigger a reload when changed
- **initialFilterText** (`string`, default: `''`) - Initial filter text value
- **initialSortDescriptor** (`SortDescriptor | null`) - Initial sort configuration

### Load Parameters

The `load` function receives an object with the following properties:

- **cursor** (`C | undefined`) - Current cursor for pagination
- **filterText** (`string`) - Current filter text
- **sortDescriptor** (`SortDescriptor | null`) - Current sort configuration
- **signal** (`AbortSignal`) - AbortController signal for request cancellation

### Load Result

The `load` function should return an object with:

- **items** (`T[]`) - The loaded items
- **cursor** (`C | undefined`) - Optional cursor for next page

### Sort Parameters

The `sort` function receives an object with:

- **items** (`T[]`) - Current items to sort
- **descriptor** (`SortDescriptor`) - Sort configuration with `column` and `direction`

### Return Value

The hook returns an object with the following properties and methods:

#### State Properties

- **items** (`T[]`) - Current list of items
- **loading** (`boolean`) - Whether a load operation is in progress
- **error** (`Error | null`) - Any error from the last operation
- **cursor** (`C | undefined`) - Current cursor for pagination
- **filterText** (`string`) - Current filter text
- **sortDescriptor** (`SortDescriptor | null`) - Current sort configuration

#### Methods

- **reload** (`() => void`) - Reload data from the beginning
- **loadMore** (`() => void`) - Load more items (when cursor is available)
- **setFilterText** (`(text: string) => void`) - Set filter text and reload
- **sort** (`(descriptor: SortDescriptor) => void`) - Apply sorting

#### Types

```tsx
interface SortDescriptor {
  column: string
  direction: 'ascending' | 'descending'
}

interface LoadParams<C> {
  cursor?: C
  filterText: string
  sortDescriptor?: SortDescriptor | null
  signal: AbortSignal
}

interface LoadResult<T, C> {
  items: T[]
  cursor?: C
}
```}
              {product.price}
            </div>
            <div class={styles.ItemMeta}>
              {product.category}
              {' • '}
              {product.rating.rate}
              {' ('}
              {product.rating.count}
              {' reviews)'}
            </div>
          </div>
        </div>
      }
    </div>
  </div>
}

```

### Dependencies

Automatically reload data when dependencies change, such as filter selections or external state.

```ripple
import { useAsyncList } from 'ark-ripple/collection';
import { Loader } from 'lucide-ripple';
import { track } from 'ripple';
import field from 'styles/field.module.css';
import styles from 'styles/async-list.module.css';

const LIMIT = 5;

interface User {
  id: number;
  name: string;
  email: string;
  department: string;
  role: string;
}

const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

const departments = ['Engineering', 'Marketing', 'Sales', 'Support'];

const roles = [
  'Senior Developer',
  'Marketing Manager',
  'Frontend Developer',
  'Sales Representative',
  'DevOps Engineer',
  'Customer Success',
  'Content Creator',
  'Backend Developer',
  'Account Manager',
  'Technical Support',
  'Brand Manager',
  'Full Stack Developer',
  'Sales Director',
  'Support Manager',
  'UI Designer',
  'Digital Marketer',
  'Mobile Developer',
  'Business Development',
  'Documentation Specialist',
  'Social Media Manager',
];

const mockUsers: User[] = [
  {
    id: 1,
    name: 'Alice Johnson',
    email: 'alice@example.com',
    department: 'Engineering',
    role: 'Senior Developer',
  },
  {
    id: 2,
    name: 'Bob Smith',
    email: 'bob@example.com',
    department: 'Marketing',
    role: 'Marketing Manager',
  },
  {
    id: 3,
    name: 'Carol Davis',
    email: 'carol@example.com',
    department: 'Engineering',
    role: 'Frontend Developer',
  },
  {
    id: 4,
    name: 'David Wilson',
    email: 'david@example.com',
    department: 'Sales',
    role: 'Sales Representative',
  },
  {
    id: 5,
    name: 'Eva Brown',
    email: 'eva@example.com',
    department: 'Engineering',
    role: 'DevOps Engineer',
  },
  {
    id: 6,
    name: 'Frank Miller',
    email: 'frank@example.com',
    department: 'Support',
    role: 'Customer Success',
  },
  {
    id: 7,
    name: 'Grace Lee',
    email: 'grace@example.com',
    department: 'Marketing',
    role: 'Content Creator',
  },
  {
    id: 8,
    name: 'Henry Taylor',
    email: 'henry@example.com',
    department: 'Engineering',
    role: 'Backend Developer',
  },
  {
    id: 9,
    name: 'Ivy Anderson',
    email: 'ivy@example.com',
    department: 'Sales',
    role: 'Account Manager',
  },
  {
    id: 10,
    name: 'Jack Thompson',
    email: 'jack@example.com',
    department: 'Support',
    role: 'Technical Support',
  },
  {
    id: 11,
    name: 'Kate Martinez',
    email: 'kate@example.com',
    department: 'Marketing',
    role: 'Brand Manager',
  },
  {
    id: 12,
    name: 'Liam Garcia',
    email: 'liam@example.com',
    department: 'Engineering',
    role: 'Full Stack Developer',
  },
  {
    id: 13,
    name: 'Mia Rodriguez',
    email: 'mia@example.com',
    department: 'Sales',
    role: 'Sales Director',
  },
  {
    id: 14,
    name: 'Noah Lopez',
    email: 'noah@example.com',
    department: 'Support',
    role: 'Support Manager',
  },
  {
    id: 15,
    name: 'Olivia White',
    email: 'olivia@example.com',
    department: 'Engineering',
    role: 'UI Designer',
  },
  {
    id: 16,
    name: 'Paul Harris',
    email: 'paul@example.com',
    department: 'Marketing',
    role: 'Digital Marketer',
  },
  {
    id: 17,
    name: 'Quinn Clark',
    email: 'quinn@example.com',
    department: 'Engineering',
    role: 'Mobile Developer',
  },
  {
    id: 18,
    name: 'Ruby Lewis',
    email: 'ruby@example.com',
    department: 'Sales',
    role: 'Business Development',
  },
  {
    id: 19,
    name: 'Sam Young',
    email: 'sam@example.com',
    department: 'Support',
    role: 'Documentation Specialist',
  },
  {
    id: 20,
    name: 'Tina Walker',
    email: 'tina@example.com',
    department: 'Marketing',
    role: 'Social Media Manager',
  },
];

export component Dependencies() {
  let selectedDepartment = track('');
  let selectedRole = track('');

  const dependencies = track(() => [@selectedDepartment, @selectedRole]);

  const list = useAsyncList<User>(
    {
      initialItems: mockUsers.slice(0, LIMIT),
      dependencies,
      async load({ filterText }: { filterText?: string }) {
        await delay(400);

        let items = mockUsers;

        if (@selectedDepartment) {
          items = items.filter((user) => user.department === @selectedDepartment);
        }

        if (@selectedRole) {
          items = items.filter((user) => user.role === @selectedRole);
        }

        if (filterText) {
          items = items.filter(
            (user) => user.name.toLowerCase().includes(filterText.toLowerCase()) ||
              user.email.toLowerCase().includes(filterText.toLowerCase()),
          );
        }

        return { items: items.slice(0, LIMIT) };
      },
    },
  );

  <div class={styles.Root}>
    <div class={styles.Header}>
      <select
        class={field.Select}
        value={@selectedDepartment}
        onChange={(e) => {
          @selectedDepartment = (e.target as HTMLSelectElement).value;
        }}
      >
        <option value="">{'All Departments'}</option>
        for (const dept of departments; key dept) {
          <option value={dept}>{dept}</option>
        }
      </select>

      <select
        class={field.Select}
        value={@selectedRole}
        onChange={(e) => {
          @selectedRole = (e.target as HTMLSelectElement).value;
        }}
      >
        <option value="">{'All Roles'}</option>
        for (const role of roles; key role) {
          <option value={role}>{role}</option>
        }
      </select>

      <input
        class={field.Input}
        type="text"
        placeholder="Search..."
        value={@list.filterText}
        onInput={(e) => {
          @list.setFilterText((e.target as HTMLInputElement).value);
        }}
      />

      if (@list.loading) {
        <span class={styles.Loading}>
          <Loader class={styles.Spinner} />
          {'Loading'}
        </span>
      }
    </div>

    if (@list.error) {
      <div class={styles.Error}>
        {'Error: '}
        {@list.error.message}
      </div>
    }

    <div class={styles.Status}>
      {'Found '}
      {@list.items.length}
      {' users'}
    </div>

    <div class={styles.ItemGroup}>
      for (const user of @list.items; key user.id) {
        <div class={styles.Item}>
          <div class={styles.ItemContent}>
            <div class={styles.ItemTitle}>{user.name}</div>
            <div class={styles.ItemDescription}>{user.email}</div>
            <div class={styles.ItemMeta}>
              {user.department}
              {' • '}
              {user.role}
            </div>
          </div>
        </div>
      }
    </div>

    if (@list.items.length === 0 && !@list.loading) {
      <div class={styles.Empty}>{'No users found with current filters'}</div>
    }
  </div>
}
```

## API Reference

### Props

- **load** (`(params: LoadParams<C>) => Promise<LoadResult<T, C>>`) - Function to load data asynchronously
- **sort** (`(params: SortParams<T>) => Promise<SortResult<T>> | SortResult<T>`) - Optional function for client-side
  sorting
- **autoReload** (`boolean`, default: `false`) - Whether to automatically reload data on mount
- **initialItems** (`T[]`, default: `[]`) - Initial items to display before first load
- **dependencies** (`any[]`, default: `[]`) - Values that trigger a reload when changed
- **initialFilterText** (`string`, default: `''`) - Initial filter text value
- **initialSortDescriptor** (`SortDescriptor | null`) - Initial sort configuration

### Load Parameters

The `load` function receives an object with the following properties:

- **cursor** (`C | undefined`) - Current cursor for pagination
- **filterText** (`string`) - Current filter text
- **sortDescriptor** (`SortDescriptor | null`) - Current sort configuration
- **signal** (`AbortSignal`) - AbortController signal for request cancellation

### Load Result

The `load` function should return an object with:

- **items** (`T[]`) - The loaded items
- **cursor** (`C | undefined`) - Optional cursor for next page

### Sort Parameters

The `sort` function receives an object with:

- **items** (`T[]`) - Current items to sort
- **descriptor** (`SortDescriptor`) - Sort configuration with `column` and `direction`

### Return Value

The hook returns an object with the following properties and methods:

#### State Properties

- **items** (`T[]`) - Current list of items
- **loading** (`boolean`) - Whether a load operation is in progress
- **error** (`Error | null`) - Any error from the last operation
- **cursor** (`C | undefined`) - Current cursor for pagination
- **filterText** (`string`) - Current filter text
- **sortDescriptor** (`SortDescriptor | null`) - Current sort configuration

#### Methods

- **reload** (`() => void`) - Reload data from the beginning
- **loadMore** (`() => void`) - Load more items (when cursor is available)
- **setFilterText** (`(text: string) => void`) - Set filter text and reload
- **sort** (`(descriptor: SortDescriptor) => void`) - Apply sorting

#### Types

```tsx
interface SortDescriptor {
  column: string
  direction: 'ascending' | 'descending'
}

interface LoadParams<C> {
  cursor?: C
  filterText: string
  sortDescriptor?: SortDescriptor | null
  signal: AbortSignal
}

interface LoadResult<T, C> {
  items: T[]
  cursor?: C
}
```


# List Selection 

The `useListSelection` hook manages selection state in lists and collections. It supports single and multiple selection
modes with operations like select, deselect, toggle, and clear.

```tsx
import { createListCollection, useListSelection } from 'ark-ripple/collection'

const collection = createListCollection({
  items: [
    { label: 'Apple', value: 'apple' },
    { label: 'Banana', value: 'banana' },
    { label: 'Cherry', value: 'cherry' },
  ],
})

const selection = useListSelection({
  collection,
  selectionMode: 'single',
  deselectable: true,
})

console.log(selection.selectedValues) // ['apple', 'banana', 'cherry']
```

## Examples

### Basic

By default, the hook supports single selection mode that can be deselected.

> Set `deselectable` to `false` to prevent deselecting the current selection.

**Example: list-selection/basic**

```ripple
import { Checkbox } from 'ark-ripple/checkbox';
import { createListCollection, useListSelection } from 'ark-ripple/collection';
import { Check } from 'lucide-ripple';
import styles from 'styles/list-selection.module.css';
import checkboxStyles from 'styles/checkbox.module.css';

const collection = createListCollection(
  {
    items: [
      { label: 'React', value: 'react' },
      { label: 'Vue', value: 'vue' },
      { label: 'Angular', value: 'angular' },
      { label: 'Svelte', value: 'svelte' },
    ],
  },
);

export component Basic() {
  const selection = useListSelection({ collection });

  <div class={styles.Root}>
    <output>
      {'Selected: '}
      {@selection.selectedValues.join(', ') || 'None'}
    </output>
    for (const item of collection.items; key item.value) {
      <Checkbox.Root
        class={styles.Item}
        data-selected={@selection.isSelected(item.value) || undefined}
        checked={@selection.isSelected(item.value)}
        onCheckedChange={() => @selection.select(item.value)}
      >
        <Checkbox.Control class={checkboxStyles.Control}>
          <Checkbox.Indicator class={checkboxStyles.Indicator}>
            <Check />
          </Checkbox.Indicator>
        </Checkbox.Control>
        <Checkbox.Label class={checkboxStyles.Label}>{item.label}</Checkbox.Label>
        <Checkbox.HiddenInput />
      </Checkbox.Root>
    }
  </div>
}

```

### Multiple Selection

Set `selectionMode` to `multiple` to allow multiple items to be selected.

**Example: list-selection/multiple**

```ripple
import { Checkbox } from 'ark-ripple/checkbox';
import { createListCollection, useListSelection } from 'ark-ripple/collection';
import { Check } from 'lucide-ripple';
import styles from 'styles/list-selection.module.css';
import checkboxStyles from 'styles/checkbox.module.css';

const collection = createListCollection(
  {
    items: [
      { label: 'React', value: 'react' },
      { label: 'Vue', value: 'vue' },
      { label: 'Angular', value: 'angular' },
      { label: 'Svelte', value: 'svelte' },
      { label: 'Solid', value: 'solid' },
    ],
  },
);

export component Multiple() {
  const selection = useListSelection({ collection, selectionMode: 'multiple' });

  const handleSelectAll = () => {
    if (@selection.isAllSelected()) {
      @selection.clear();
    } else {
      @selection.setSelectedValues(collection.getValues());
    }
  };

  <div class={styles.Root}>
    <div class={styles.Header}>
      <span class={styles.Count}>
        {@selection.selectedValues.length}
        {' of '}
        {collection.items.length}
        {' selected'}
      </span>
      <button type="button" class={styles.SelectAllButton} onClick={handleSelectAll}>
        {@selection.isAllSelected() ? 'Deselect all' : 'Select all'}
      </button>
    </div>
    for (const item of collection.items; key item.value) {
      <Checkbox.Root
        class={styles.Item}
        data-selected={@selection.isSelected(item.value) || undefined}
        checked={@selection.isSelected(item.value)}
        onCheckedChange={() => @selection.select(item.value)}
      >
        <Checkbox.Control class={checkboxStyles.Control}>
          <Checkbox.Indicator class={checkboxStyles.Indicator}>
            <Check />
          </Checkbox.Indicator>
        </Checkbox.Control>
        <Checkbox.Label class={checkboxStyles.Label}>{item.label}</Checkbox.Label>
        <Checkbox.HiddenInput />
      </Checkbox.Root>
    }
  </div>
}

```

### Range Selection

Here's an example of how to implement range selection that extends the selection from the first selected item to the
clicked item.

**Example: list-selection/range**

```ripple
import { Checkbox } from 'ark-ripple/checkbox';
import { createListCollection, useListSelection } from 'ark-ripple/collection';
import { Check } from 'lucide-ripple';
import styles from 'styles/list-selection.module.css';
import checkboxStyles from 'styles/checkbox.module.css';

const collection = createListCollection(
  {
    items: [
      { label: 'React', value: 'react' },
      { label: 'Vue', value: 'vue' },
      { label: 'Angular', value: 'angular' },
      { label: 'Svelte', value: 'svelte' },
      { label: 'Solid', value: 'solid' },
    ],
  },
);

export component Range() {
  const selection = useListSelection({ collection, selectionMode: 'multiple' });

  const handleItemClick = (value: string, event: MouseEvent) => {
    event.preventDefault();
    const firstSelected = @selection.firstSelectedValue;
    if (event.shiftKey && firstSelected) {
      @selection.extend(firstSelected, value);
    } else if (event.ctrlKey || event.metaKey) {
      @selection.toggle(value);
    } else {
      @selection.replace(value);
    }
  };

  <div class={styles.Root}>
    <output>
      {'Selected: '}
      {@selection.selectedValues.join(', ') || 'None'}
    </output>
    for (const item of collection.items; key item.value) {
      <Checkbox.Root
        class={styles.Item}
        data-selected={@selection.isSelected(item.value) || undefined}
        checked={@selection.isSelected(item.value)}
        onClick={(e) => handleItemClick(item.value, e)}
      >
        <Checkbox.Control class={checkboxStyles.Control}>
          <Checkbox.Indicator class={checkboxStyles.Indicator}>
            <Check />
          </Checkbox.Indicator>
        </Checkbox.Control>
        <Checkbox.Label class={checkboxStyles.Label}>{item.label}</Checkbox.Label>
        <Checkbox.HiddenInput />
      </Checkbox.Root>
    }
    <p class={styles.HelperText}>
      {'Click to select • Shift+Click for range • Cmd/Ctrl+Click to toggle'}
    </p>
  </div>
}

```

## API Reference

### Props

- **collection** (`ListCollection<T>`) - The collection to manage selection for
- **selectionMode** (`'single' | 'multiple' | 'none'`, default: `'single'`) - The selection mode
- **deselectable** (`boolean`, default: `true`) - Whether selected items can be deselected
- **initialSelectedValues** (`string[]`, default: `[]`) - Initial selected values
- **resetOnCollectionChange** (`boolean`, default: `false`) - Whether to reset selection when collection changes

### Return Value

The hook returns an object with the following properties and methods:

#### State Properties

- **selectedValues** (`string[]`) - Array of currently selected values
- **isEmpty** (`boolean`) - Whether no items are selected
- **firstSelectedValue** (`string | null`) - The first selected value in collection order
- **lastSelectedValue** (`string | null`) - The last selected value in collection order

#### Query Methods

- **isSelected** (`(value: string | null) => boolean`) - Check if a value is selected
- **canSelect** (`(value: string) => boolean`) - Check if a value can be selected
- **isAllSelected** (`() => boolean`) - Check if all items are selected
- **isSomeSelected** (`() => boolean`) - Check if some items are selected

#### Selection Methods

- **select** (`(value: string, forceToggle?: boolean) => void`) - Select a value
- **deselect** (`(value: string) => void`) - Deselect a value
- **toggle** (`(value: string) => void`) - Toggle selection of a value
- **replace** (`(value: string | null) => void`) - Replace selection with a single value
- **extend** (`(anchorValue: string, targetValue: string) => void`) - Extend selection from anchor to target
- **setSelectedValues** (`(values: string[]) => void`) - Set the selected values
- **setSelection** (`(values: string[]) => void`) - Set the selection (alias for setSelectedValues)
- **clear** (`() => void`) - Clear all selections
- **resetSelection** (`() => void`) - Reset selection to initial state



# COMPONENTS

---

# Accordion 



## Anatomy



```tsx
<Accordion.Root>
  <Accordion.Item>
    <Accordion.ItemTrigger>
      <Accordion.ItemIndicator />
    </Accordion.ItemTrigger>
    <Accordion.ItemContent />
  </Accordion.Item>
</Accordion.Root>
```

## Examples

### Default Value

Set the `defaultValue` prop to specify which item should be expanded by default.

**Example: basic**

```ripple
import { Accordion } from 'ark-ripple/accordion';
import { ChevronDown } from 'lucide-ripple';
import styles from 'styles/accordion.module.css';

export component Basic() {
  <Accordion.Root class={styles.Root} defaultValue={['ark-ui']}>
    for (const item of items; key item.value) {
      <Accordion.Item class={styles.Item} value={item.value}>
        <Accordion.ItemTrigger class={styles.ItemTrigger}>
          {item.title}
          <Accordion.ItemIndicator class={styles.ItemIndicator}>
            <ChevronDown />
          </Accordion.ItemIndicator>
        </Accordion.ItemTrigger>
        <Accordion.ItemContent class={styles.ItemContent}>
          <div class={styles.ItemBody}>{item.content}</div>
        </Accordion.ItemContent>
      </Accordion.Item>
    }
  </Accordion.Root>
}

const items = [
  {
    value: 'ark-ui',
    title: 'What is Ark UI?',
    content: 'A headless component library for building accessible web apps.',
  },
  {
    value: 'getting-started',
    title: 'How to get started?',
    content: 'Install the package and import the components you need.',
  },
  {
    value: 'maintainers',
    title: 'Who maintains this project?',
    content: 'Ark UI is maintained by the Chakra UI team.',
  },
];

```

### Controlled

Use the `value` and `onValueChange` props to control the expanded items.

**Example: controlled**

```ripple
import { Accordion } from 'ark-ripple/accordion';
import { track } from 'ripple';
import { ChevronDown } from 'lucide-ripple';
import styles from 'styles/accordion.module.css';

export component Controlled() {
  let value = track<string[]>([]);

  <Accordion.Root
    class={styles.Root}
    {value}
    onValueChange={(details) => {
      @value = details.value;
    }}
  >
    for (const item of items; key item.value) {
      <Accordion.Item class={styles.Item} value={item.value}>
        <Accordion.ItemTrigger class={styles.ItemTrigger}>
          {item.title}
          <Accordion.ItemIndicator class={styles.ItemIndicator}>
            <ChevronDown />
          </Accordion.ItemIndicator>
        </Accordion.ItemTrigger>
        <Accordion.ItemContent class={styles.ItemContent}>
          <div class={styles.ItemBody}>{item.content}</div>
        </Accordion.ItemContent>
      </Accordion.Item>
    }
  </Accordion.Root>
}

const items = [
  {
    value: 'ark-ui',
    title: 'What is Ark UI?',
    content: 'A headless component library for building accessible web apps.',
  },
  {
    value: 'getting-started',
    title: 'How to get started?',
    content: 'Install the package and import the components you need.',
  },
  {
    value: 'maintainers',
    title: 'Who maintains this project?',
    content: 'Ark UI is maintained by the Chakra UI team.',
  },
];

```

### Root Provider

An alternative way to control the accordion is to use the `RootProvider` component and the `useAccordion` hook. This way
you can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { Accordion } from 'ark-ripple/accordion';
import { useAccordion } from 'ark-ripple/accordion';
import { ChevronDown } from 'lucide-ripple';
import styles from 'styles/accordion.module.css';

export component RootProvider() {
  const accordion = useAccordion({ multiple: true, defaultValue: ['ark-ui'] });

  <div class="stack">
    <output>
      {'Value: '}
      {JSON.stringify(@accordion.value)}
    </output>

    <Accordion.RootProvider class={styles.Root} value={accordion}>
      for (const item of items; key item.value) {
        <Accordion.Item class={styles.Item} value={item.value}>
          <Accordion.ItemTrigger class={styles.ItemTrigger}>
            {item.title}
            <Accordion.ItemIndicator class={styles.ItemIndicator}>
              <ChevronDown />
            </Accordion.ItemIndicator>
          </Accordion.ItemTrigger>
          <Accordion.ItemContent class={styles.ItemContent}>
            <div class={styles.ItemBody}>{item.content}</div>
          </Accordion.ItemContent>
        </Accordion.Item>
      }
    </Accordion.RootProvider>
  </div>
}

const items = [
  {
    value: 'ark-ui',
    title: 'What is Ark UI?',
    content: 'A headless component library for building accessible web apps.',
  },
  {
    value: 'getting-started',
    title: 'How to get started?',
    content: 'Install the package and import the components you need.',
  },
  {
    value: 'maintainers',
    title: 'Who maintains this project?',
    content: 'Ark UI is maintained by the Chakra UI team.',
  },
];

```

### Collapsible

Use the `collapsible` prop to allow the user to collapse all panels.

**Example: collapsible**

```ripple
import { Accordion } from 'ark-ripple/accordion';
import { ChevronDown } from 'lucide-ripple';
import styles from 'styles/accordion.module.css';

export component Collapsible() {
  <Accordion.Root class={styles.Root} defaultValue={['ark-ui']} collapsible>
    for (const item of items; key item.value) {
      <Accordion.Item class={styles.Item} value={item.value}>
        <Accordion.ItemTrigger class={styles.ItemTrigger}>
          {item.title}
          <Accordion.ItemIndicator class={styles.ItemIndicator}>
            <ChevronDown />
          </Accordion.ItemIndicator>
        </Accordion.ItemTrigger>
        <Accordion.ItemContent class={styles.ItemContent}>
          <div class={styles.ItemBody}>{item.content}</div>
        </Accordion.ItemContent>
      </Accordion.Item>
    }
  </Accordion.Root>
}

const items = [
  {
    value: 'ark-ui',
    title: 'What is Ark UI?',
    content: 'A headless component library for building accessible web apps.',
  },
  {
    value: 'getting-started',
    title: 'How to get started?',
    content: 'Install the package and import the components you need.',
  },
  {
    value: 'maintainers',
    title: 'Who maintains this project?',
    content: 'Ark UI is maintained by the Chakra UI team.',
  },
];

```

### Multiple

Use the `multiple` prop to allow multiple panels to be expanded simultaneously.

**Example: multiple**

```ripple
import { Accordion } from 'ark-ripple/accordion';
import { ChevronDown } from 'lucide-ripple';
import styles from 'styles/accordion.module.css';

export component Multiple() {
  <Accordion.Root class={styles.Root} defaultValue={['ark-ui']} multiple>
    for (const item of items; key item.value) {
      <Accordion.Item class={styles.Item} value={item.value}>
        <Accordion.ItemTrigger class={styles.ItemTrigger}>
          {item.title}
          <Accordion.ItemIndicator class={styles.ItemIndicator}>
            <ChevronDown />
          </Accordion.ItemIndicator>
        </Accordion.ItemTrigger>
        <Accordion.ItemContent class={styles.ItemContent}>
          <div class={styles.ItemBody}>{item.content}</div>
        </Accordion.ItemContent>
      </Accordion.Item>
    }
  </Accordion.Root>
}

const items = [
  {
    value: 'ark-ui',
    title: 'What is Ark UI?',
    content: 'A headless component library for building accessible web apps.',
  },
  {
    value: 'getting-started',
    title: 'How to get started?',
    content: 'Install the package and import the components you need.',
  },
  {
    value: 'maintainers',
    title: 'Who maintains this project?',
    content: 'Ark UI is maintained by the Chakra UI team.',
  },
];

```

### Horizontal

By default, the Accordion is oriented vertically. Use the `orientation` prop to switch to a horizontal layout.

**Example: horizontal**

```ripple
import { Accordion } from 'ark-ripple/accordion';
import styles from 'styles/accordion.module.css';

export component Horizontal() {
  <Accordion.Root class={styles.Root} defaultValue={['ark-ui']} orientation="horizontal">
    for (const item of items; key item.value) {
      <Accordion.Item class={styles.Item} value={item.value}>
        <Accordion.ItemTrigger class={styles.ItemTrigger}>{item.title}</Accordion.ItemTrigger>
        <Accordion.ItemContent class={styles.ItemContent}>
          <div class={styles.ItemBody}>{item.content}</div>
        </Accordion.ItemContent>
      </Accordion.Item>
    }
  </Accordion.Root>
}

const items = [
  {
    value: 'ark-ui',
    title: 'What is Ark UI?',
    content: 'A headless component library for building accessible web apps.',
  },
  {
    value: 'getting-started',
    title: 'How to get started?',
    content: 'Install the package and import the components you need.',
  },
  {
    value: 'maintainers',
    title: 'Who maintains this project?',
    content: 'Ark UI is maintained by the Chakra UI team.',
  },
];

```

### Lazy Mount

Use the `lazyMount` prop to defer rendering of accordion content until the item is expanded. Combine with
`unmountOnExit` to unmount content when collapsed, freeing up resources.

**Example: lazy-mount**

```ripple
import { Accordion } from 'ark-ripple/accordion';
import { ChevronDown } from 'lucide-ripple';
import styles from 'styles/accordion.module.css';

export component LazyMount() {
  <Accordion.Root class={styles.Root} lazyMount unmountOnExit>
    for (const item of items; key item.value) {
      <Accordion.Item class={styles.Item} value={item.value}>
        <Accordion.ItemTrigger class={styles.ItemTrigger}>
          {item.title}
          <Accordion.ItemIndicator class={styles.ItemIndicator}>
            <ChevronDown />
          </Accordion.ItemIndicator>
        </Accordion.ItemTrigger>
        <Accordion.ItemContent class={styles.ItemContent}>
          <div class={styles.ItemBody}>{item.content}</div>
        </Accordion.ItemContent>
      </Accordion.Item>
    }
  </Accordion.Root>
}

const items = [
  {
    value: 'ark-ui',
    title: 'What is Ark UI?',
    content: 'A headless component library for building accessible web apps.',
  },
  {
    value: 'getting-started',
    title: 'How to get started?',
    content: 'Install the package and import the components you need.',
  },
  {
    value: 'maintainers',
    title: 'Who maintains this project?',
    content: 'Ark UI is maintained by the Chakra UI team.',
  },
];

```

### Context

Use `Accordion.Context` or `useAccordionContext` to access the accordion state.

**Example: context**

```ripple
import { Accordion } from 'ark-ripple/accordion';
import { ChevronDown } from 'lucide-ripple';
import styles from 'styles/accordion.module.css';

export component Context() {
  <Accordion.Root class={styles.Root} defaultValue={['ark-ui']}>
    <Accordion.Context>
      component children({ context }) {
        <output>
          <div>
            {'context.value: '}
            {JSON.stringify(@context.value)}
          </div>
          <div>
            {'context.focusedValue: '}
            {@context.focusedValue || 'null'}
          </div>
        </output>
      }
    </Accordion.Context>
    for (const item of items; key item.value) {
      <Accordion.Item class={styles.Item} value={item.value}>
        <Accordion.ItemTrigger class={styles.ItemTrigger}>
          {item.title}
          <Accordion.ItemIndicator class={styles.ItemIndicator}>
            <ChevronDown />
          </Accordion.ItemIndicator>
        </Accordion.ItemTrigger>
        <Accordion.ItemContent class={styles.ItemContent}>
          <div class={styles.ItemBody}>{item.content}</div>
        </Accordion.ItemContent>
      </Accordion.Item>
    }
  </Accordion.Root>
}

const items = [
  {
    value: 'ark-ui',
    title: 'What is Ark UI?',
    content: 'A headless component library for building accessible web apps.',
  },
  {
    value: 'getting-started',
    title: 'How to get started?',
    content: 'Install the package and import the components you need.',
  },
  {
    value: 'maintainers',
    title: 'Who maintains this project?',
    content: 'Ark UI is maintained by the Chakra UI team.',
  },
];

```

### Item State

Use `Accordion.ItemContext` or `useAccordionItemContext` to access the state of an accordion item.

**Example: item-context**

```ripple
import { Accordion } from 'ark-ripple/accordion';
import { ChevronDown } from 'lucide-ripple';
import styles from 'styles/accordion.module.css';

export component ItemContext() {
  <Accordion.Root class={styles.Root} defaultValue={['ark-ui']}>
    for (const item of items; key item.value) {
      <Accordion.Item class={styles.Item} value={item.value}>
        <Accordion.ItemTrigger class={styles.ItemTrigger}>
          {item.title}
          <Accordion.ItemIndicator class={styles.ItemIndicator}>
            <ChevronDown />
          </Accordion.ItemIndicator>
          <Accordion.ItemContext>
            component children({ context }) {
              <code style="display:inline-flex;gap:0.5rem;font-size:0.75rem">
                if (@context.expanded) {
                  <span>{'Expanded'}</span>
                }
                if (@context.focused) {
                  <span>{'Focused'}</span>
                }
              </code>
            }
          </Accordion.ItemContext>
        </Accordion.ItemTrigger>
        <Accordion.ItemContent class={styles.ItemContent}>
          <div class={styles.ItemBody}>{item.content}</div>
        </Accordion.ItemContent>
      </Accordion.Item>
    }
  </Accordion.Root>
}

const items = [
  {
    value: 'ark-ui',
    title: 'What is Ark UI?',
    content: 'A headless component library for building accessible web apps.',
  },
  {
    value: 'getting-started',
    title: 'How to get started?',
    content: 'Install the package and import the components you need.',
  },
  {
    value: 'maintainers',
    title: 'Who maintains this project?',
    content: 'Ark UI is maintained by the Chakra UI team.',
  },
];

```

## Guides

### Content Animation

Use the `--height` and/or `--width` CSS variables to animate the size of the content when it expands or closes:

```css
@keyframes slideDown {
  from {
    opacity: 0.01;
    height: 0;
  }
  to {
    opacity: 1;
    height: var(--height);
  }
}

@keyframes slideUp {
  from {
    opacity: 1;
    height: var(--height);
  }
  to {
    opacity: 0.01;
    height: 0;
  }
}

[data-scope='accordion'][data-part='item-content'][data-state='open'] {
  animation: slideDown 250ms ease-in-out;
}

[data-scope='accordion'][data-part='item-content'][data-state='closed'] {
  animation: slideUp 200ms ease-in-out;
}
```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `collapsible` | `boolean` | No | Whether an accordion item can be closed after it has been expanded. |
| `defaultValue` | `string[]` | No | The initial value of the expanded accordion items.
Use when you don't need to control the value of the accordion. |
| `disabled` | `boolean` | No | Whether the accordion items are disabled |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{
  root: string
  item: (value: string) => string
  itemContent: (value: string) => string
  itemTrigger: (value: string) => string
}>` | No | The ids of the elements in the accordion. Useful for composition. |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `multiple` | `boolean` | No | Whether multiple accordion items can be expanded at the same time. |
| `onFocusChange` | `(details: FocusChangeDetails) => void` | No | The callback fired when the focused accordion item changes. |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | The callback fired when the state of expanded/collapsed accordion items changes. |
| `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the accordion items. |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |
| `value` | `string[]` | No | The controlled value of the expanded accordion items. |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | accordion |
| `[data-part]` | root |
| `[data-orientation]` | The orientation of the accordion |


**ItemContent Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemContent Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | accordion |
| `[data-part]` | item-content |
| `[data-state]` | "open" | "closed" |
| `[data-disabled]` | Present when disabled |
| `[data-focus]` | Present when focused |
| `[data-orientation]` | The orientation of the item |


**ItemIndicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemIndicator Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | accordion |
| `[data-part]` | item-indicator |
| `[data-state]` | "open" | "closed" |
| `[data-disabled]` | Present when disabled |
| `[data-focus]` | Present when focused |
| `[data-orientation]` | The orientation of the item |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `string` | Yes | The value of the accordion item. |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `disabled` | `boolean` | No | Whether the accordion item is disabled. |


**Item Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | accordion |
| `[data-part]` | item |
| `[data-state]` | "open" | "closed" |
| `[data-focus]` | Present when focused |
| `[data-disabled]` | Present when disabled |
| `[data-orientation]` | The orientation of the item |


**ItemTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | accordion |
| `[data-part]` | item-trigger |
| `[data-controls]` |  |
| `[data-orientation]` | The orientation of the item |
| `[data-state]` | "open" | "closed" |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseAccordionReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `focusedValue` | `string` | The value of the focused accordion item. |
| `value` | `string[]` | The value of the accordion |
| `setValue` | `(value: string[]) => void` | Sets the value of the accordion |
| `getItemState` | `(props: ItemProps) => ItemState` | Returns the state of an accordion item. |


## Accessibility

This component complies with the
[Accordion WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/).

### Keyboard Support

**`Space`**
Description: When focus is on an trigger of a collapsed item, the item is expanded

**`Enter`**
Description: When focus is on an trigger of a collapsed section, expands the section.

**`Tab`**
Description: Moves focus to the next focusable element

**`Shift + Tab`**
Description: Moves focus to the previous focusable element

**`ArrowDown`**
Description: Moves focus to the next trigger

**`ArrowUp`**
Description: Moves focus to the previous trigger.

**`Home`**
Description: When focus is on an trigger, moves focus to the first trigger.

**`End`**
Description: When focus is on an trigger, moves focus to the last trigger.


# Angle Slider 



## Anatomy



```tsx
<AngleSlider.Root>
  <AngleSlider.Label />
  <AngleSlider.Control>
    <AngleSlider.Thumb />
    <AngleSlider.MarkerGroup>
      <AngleSlider.Marker />
    </AngleSlider.MarkerGroup>
  </AngleSlider.Control>
  <AngleSlider.ValueText />
  <AngleSlider.HiddenInput />
</AngleSlider.Root>
```

## Examples

### Basic

Here's a basic example of the Angle Slider component.

**Example: basic**

```ripple
import { AngleSlider } from 'ark-ripple/angle-slider';
import styles from 'styles/angle-slider.module.css';

const markers = [0, 45, 90, 135, 180, 225, 270, 315];

export component Basic() {
  <AngleSlider.Root class={styles.Root}>
    <AngleSlider.Label class={styles.Label}>{'Rotation'}</AngleSlider.Label>
    <AngleSlider.Control class={styles.Control}>
      <AngleSlider.MarkerGroup class={styles.MarkerGroup}>
        for (const value of markers; key value) {
          <AngleSlider.Marker {value} class={styles.Marker} />
        }
      </AngleSlider.MarkerGroup>
      <AngleSlider.Thumb class={styles.Thumb} />
    </AngleSlider.Control>
    <AngleSlider.ValueText class={styles.ValueText} />
    <AngleSlider.HiddenInput />
  </AngleSlider.Root>
}

```

### Controlled

Use the `value` and `onValueChange` props to control the value of the Angle Slider.

**Example: controlled**

```ripple
import { AngleSlider } from 'ark-ripple/angle-slider';
import { track } from 'ripple';
import styles from 'styles/angle-slider.module.css';

const markers = [0, 45, 90, 135, 180, 225, 270, 315];

export component Controlled() {
  let value = track(45);

  <AngleSlider.Root
    class={styles.Root}
    {value}
    onValueChange={(e) => {
      @value = e.value;
    }}
  >
    <AngleSlider.Label class={styles.Label}>{'Rotation'}</AngleSlider.Label>
    <AngleSlider.Control class={styles.Control}>
      <AngleSlider.MarkerGroup class={styles.MarkerGroup}>
        for (const marker of markers; key marker) {
          <AngleSlider.Marker value={marker} class={styles.Marker} />
        }
      </AngleSlider.MarkerGroup>
      <AngleSlider.Thumb class={styles.Thumb} />
    </AngleSlider.Control>
    <AngleSlider.ValueText class={styles.ValueText} />
    <AngleSlider.HiddenInput />
  </AngleSlider.Root>
}

```

### Steps

Use the `step` prop to set the discrete steps of the Angle Slider.

**Example: step**

```ripple
import { AngleSlider } from 'ark-ripple/angle-slider';
import styles from 'styles/angle-slider.module.css';

const markers = [0, 45, 90, 135, 180, 225, 270, 315];

export component Step() {
  <AngleSlider.Root class={styles.Root} step={15}>
    <AngleSlider.Label class={styles.Label}>{'15 Step'}</AngleSlider.Label>
    <AngleSlider.Control class={styles.Control}>
      <AngleSlider.MarkerGroup class={styles.MarkerGroup}>
        for (const value of markers; key value) {
          <AngleSlider.Marker {value} class={styles.Marker} />
        }
      </AngleSlider.MarkerGroup>
      <AngleSlider.Thumb class={styles.Thumb} />
    </AngleSlider.Control>
    <AngleSlider.ValueText class={styles.ValueText} />
    <AngleSlider.HiddenInput />
  </AngleSlider.Root>
}

```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `aria-label` | `string` | No | The accessible label for the slider thumb. |
| `aria-labelledby` | `string` | No | The id of the element that labels the slider thumb. |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `defaultValue` | `number` | No | The initial value of the slider.
Use when you don't need to control the value of the slider. |
| `disabled` | `boolean` | No | Whether the slider is disabled. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{
  root: string
  thumb: string
  hiddenInput: string
  control: string
  valueText: string
  label: string
}>` | No | The ids of the elements in the machine.
Useful for composition. |
| `invalid` | `boolean` | No | Whether the slider is invalid. |
| `name` | `string` | No | The name of the slider. Useful for form submission. |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | The callback function for when the value changes. |
| `onValueChangeEnd` | `(details: ValueChangeDetails) => void` | No | The callback function for when the value changes ends. |
| `readOnly` | `boolean` | No | Whether the slider is read-only. |
| `step` | `number` | No | The step value for the slider. |
| `value` | `number` | No | The value of the slider. |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | angle-slider |
| `[data-part]` | root |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]` | Present when invalid |
| `[data-readonly]` | Present when read-only |


**Root CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--value` | The current value |
| `--angle` | The angle in degrees |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | angle-slider |
| `[data-part]` | control |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]` | Present when invalid |
| `[data-readonly]` | Present when read-only |


**HiddenInput Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | angle-slider |
| `[data-part]` | label |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]` | Present when invalid |
| `[data-readonly]` | Present when read-only |


**MarkerGroup Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Marker Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `number` | Yes | The value of the marker |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Marker Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | angle-slider |
| `[data-part]` | marker |
| `[data-value]` | The value of the item |
| `[data-state]` |  |
| `[data-disabled]` | Present when disabled |


**Marker CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--marker-value` | The logical marker value (e.g. 0, 45, 90) |
| `--marker-display-value` | The rotation angle for display (mirrored in RTL) |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseAngleSliderReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Thumb Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Thumb Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | angle-slider |
| `[data-part]` | thumb |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]` | Present when invalid |
| `[data-readonly]` | Present when read-only |


**ValueText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `value` | `number` | The current value of the angle slider |
| `valueAsDegree` | `string` | The current value as a degree string |
| `setValue` | `(value: number) => void` | Sets the value of the angle slider |
| `dragging` | `boolean` | Whether the slider is being dragged. |



# Avatar 



## Anatomy



```tsx
<Avatar.Root>
  <Avatar.Fallback />
  <Avatar.Image />
</Avatar.Root>
```

## Examples

### Basic

Display a user's profile image with a fallback.

**Example: basic**

```ripple
import { Avatar } from 'ark-ripple/avatar';
import styles from 'styles/avatar.module.css';

export component Basic() {
  <Avatar.Root class={styles.Root}>
    <Avatar.Fallback class={styles.Fallback}>{'PA'}</Avatar.Fallback>
    <Avatar.Image class={styles.Image} src="https://i.pravatar.cc/300?u=a" alt="avatar" />
  </Avatar.Root>
}

```

### Events

Use `onStatusChange` to listen for loading state changes.

**Example: events**

```ripple
import { Avatar } from 'ark-ripple/avatar';
import { track } from 'ripple';
import styles from 'styles/avatar.module.css';

export component Events() {
  let status = track('loading...');

  <div class="vstack">
    <output>
      {'Status: '}
      {@status}
    </output>
    <Avatar.Root
      class={styles.Root}
      onStatusChange={(e) => {
        @status = e.status;
      }}
    >
      <Avatar.Fallback class={styles.Fallback}>{'PA'}</Avatar.Fallback>
      <Avatar.Image class={styles.Image} src="https://i.pravatar.cc/3000?u=a" alt="avatar" />
    </Avatar.Root>
  </div>
}

```

### Root Provider

An alternative way to control the avatar is to use the `RootProvider` component and the `useAvatar` hook. This way you
can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { Avatar } from 'ark-ripple/avatar';
import { useAvatar } from 'ark-ripple/avatar';
import { track } from 'ripple';
import button from 'styles/button.module.css';
import styles from 'styles/avatar.module.css';

export component RootProvider() {
  let count = track(0);
  const avatar = useAvatar();

  <div class="vstack">
    <button
      class={button.Root}
      onClick={() => {
        @count = @count + 1;
      }}
    >
      {'Change Avatar'}
    </button>

    <Avatar.RootProvider class={styles.Root} value={avatar}>
      <Avatar.Fallback class={styles.Fallback}>{'PA'}</Avatar.Fallback>
      <Avatar.Image
        class={styles.Image}
        src={`https://i.pravatar.cc/300?u=${@count}`}
        alt="avatar"
      />
    </Avatar.RootProvider>
  </div>
}

```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ids` | `Partial<{ root: string; image: string; fallback: string }>` | No | The ids of the elements in the avatar. Useful for composition. |
| `onStatusChange` | `(details: StatusChangeDetails) => void` | No | Functional called when the image loading status changes. |


**Fallback Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Fallback Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | avatar |
| `[data-part]` | fallback |
| `[data-state]` | "hidden" | "visible" |


**Image Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Image Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | avatar |
| `[data-part]` | image |
| `[data-state]` | "visible" | "hidden" |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseAvatarReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `loaded` | `boolean` | Whether the image is loaded. |
| `setSrc` | `(src: string) => void` | Function to set new src. |
| `setLoaded` | `VoidFunction` | Function to set loaded state. |
| `setError` | `VoidFunction` | Function to set error state. |



# Carousel 



## Anatomy



```tsx
<Carousel.Root>
  <Carousel.Control>
    <Carousel.PrevTrigger />
    <Carousel.NextTrigger />
  </Carousel.Control>
  <Carousel.ItemGroup>
    <Carousel.Item />
  </Carousel.ItemGroup>
  <Carousel.IndicatorGroup>
    <Carousel.Indicator />
  </Carousel.IndicatorGroup>
</Carousel.Root>
```

## Examples

**Example: basic**

```ripple
import { Carousel } from 'ark-ripple/carousel';
import styles from 'styles/carousel.module.css';

const images = [
  { src: 'https://picsum.photos/seed/1/500/300', alt: 'Nature landscape', index: 0 },
  { src: 'https://picsum.photos/seed/2/500/300', alt: 'City skyline', index: 1 },
  { src: 'https://picsum.photos/seed/3/500/300', alt: 'Mountain view', index: 2 },
  { src: 'https://picsum.photos/seed/4/500/300', alt: 'Ocean sunset', index: 3 },
  { src: 'https://picsum.photos/seed/5/500/300', alt: 'Forest path', index: 4 },
];

export component Basic() {
  <Carousel.Root class={styles.Root} slideCount={images.length}>
    <Carousel.Control class={styles.Control}>
      <Carousel.PrevTrigger class={styles.Trigger}>{'←'}</Carousel.PrevTrigger>
      <Carousel.ItemGroup class={styles.ItemGroup}>
        for (const image of images; key image.index) {
          <Carousel.Item class={styles.Item} index={image.index}>
            <img src={image.src} alt={image.alt} width="500" height="300" />
          </Carousel.Item>
        }
      </Carousel.ItemGroup>
      <Carousel.NextTrigger class={styles.Trigger}>{'→'}</Carousel.NextTrigger>
    </Carousel.Control>
    <Carousel.IndicatorGroup class={styles.IndicatorGroup}>
      for (const image of images; key image.index) {
        <Carousel.Indicator class={styles.Indicator} index={image.index} />
      }
    </Carousel.IndicatorGroup>
  </Carousel.Root>
}

```

### Controlled

To create a controlled Carousel component, you can manage the state of the carousel using the `page` prop and update it
when the `onPageChange` event handler is called:

**Example: controlled**

```ripple
import { Carousel } from 'ark-ripple/carousel';
import { track } from 'ripple';
import styles from 'styles/carousel.module.css';

const images = [
  { src: 'https://picsum.photos/seed/1/500/300', alt: 'Nature landscape', index: 0 },
  { src: 'https://picsum.photos/seed/2/500/300', alt: 'City skyline', index: 1 },
  { src: 'https://picsum.photos/seed/3/500/300', alt: 'Mountain view', index: 2 },
  { src: 'https://picsum.photos/seed/4/500/300', alt: 'Ocean sunset', index: 3 },
  { src: 'https://picsum.photos/seed/5/500/300', alt: 'Forest path', index: 4 },
];

export component Controlled() {
  let page = track(0);

  <Carousel.Root
    class={styles.Root}
    slideCount={images.length}
    {page}
    onPageChange={(e) => {
      @page = e.page;
    }}
  >
    <Carousel.Control class={styles.Control}>
      <Carousel.PrevTrigger class={styles.Trigger}>{'←'}</Carousel.PrevTrigger>
      <Carousel.ItemGroup class={styles.ItemGroup}>
        for (const image of images; key image.index) {
          <Carousel.Item class={styles.Item} index={image.index}>
            <img src={image.src} alt={image.alt} width="500" height="300" />
          </Carousel.Item>
        }
      </Carousel.ItemGroup>
      <Carousel.NextTrigger class={styles.Trigger}>{'→'}</Carousel.NextTrigger>
    </Carousel.Control>
    <Carousel.IndicatorGroup class={styles.IndicatorGroup}>
      for (const image of images; key image.index) {
        <Carousel.Indicator class={styles.Indicator} index={image.index} />
      }
    </Carousel.IndicatorGroup>
  </Carousel.Root>
}

```

### Root Provider

An alternative way to control the carousel is to use the `RootProvider` component and the `useCarousel` hook. This way
you can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { Carousel } from 'ark-ripple/carousel';
import { useCarousel } from 'ark-ripple/carousel';
import styles from 'styles/carousel.module.css';

const images = [
  { src: 'https://picsum.photos/seed/1/500/300', alt: 'Nature landscape', index: 0 },
  { src: 'https://picsum.photos/seed/2/500/300', alt: 'City skyline', index: 1 },
  { src: 'https://picsum.photos/seed/3/500/300', alt: 'Mountain view', index: 2 },
  { src: 'https://picsum.photos/seed/4/500/300', alt: 'Ocean sunset', index: 3 },
  { src: 'https://picsum.photos/seed/5/500/300', alt: 'Forest path', index: 4 },
];

export component RootProvider() {
  const carousel = useCarousel({ slideCount: images.length });

  <div class="vstack">
    <output>
      {'Page: '}
      {@carousel.page}
    </output>
    <Carousel.RootProvider value={carousel} class={styles.Root}>
      <Carousel.Control class={styles.Control}>
        <Carousel.PrevTrigger class={styles.Trigger}>{'←'}</Carousel.PrevTrigger>
        <Carousel.ItemGroup class={styles.ItemGroup}>
          for (const image of images; key image.index) {
            <Carousel.Item class={styles.Item} index={image.index}>
              <img src={image.src} alt={image.alt} width="500" height="300" />
            </Carousel.Item>
          }
        </Carousel.ItemGroup>
        <Carousel.NextTrigger class={styles.Trigger}>{'→'}</Carousel.NextTrigger>
      </Carousel.Control>
      <Carousel.IndicatorGroup class={styles.IndicatorGroup}>
        for (const image of images; key image.index) {
          <Carousel.Indicator class={styles.Indicator} index={image.index} />
        }
      </Carousel.IndicatorGroup>
    </Carousel.RootProvider>
  </div>
}

```

### Autoplay

Pass the `autoplay` and `loop` props to `Carousel.Root` to make the carousel play automatically.

**Example: autoplay**

```ripple
import { Carousel } from 'ark-ripple/carousel';
import styles from 'styles/carousel.module.css';

const images = [
  { src: 'https://picsum.photos/seed/1/500/300', alt: 'Nature landscape', index: 0 },
  { src: 'https://picsum.photos/seed/2/500/300', alt: 'City skyline', index: 1 },
  { src: 'https://picsum.photos/seed/3/500/300', alt: 'Mountain view', index: 2 },
  { src: 'https://picsum.photos/seed/4/500/300', alt: 'Ocean sunset', index: 3 },
  { src: 'https://picsum.photos/seed/5/500/300', alt: 'Forest path', index: 4 },
];

export component Autoplay() {
  <Carousel.Root class={styles.Root} slideCount={images.length} autoplay loop>
    <Carousel.ItemGroup class={styles.ItemGroup}>
      for (const image of images; key image.index) {
        <Carousel.Item class={styles.Item} index={image.index}>
          <img src={image.src} alt={image.alt} width="500" height="300" />
        </Carousel.Item>
      }
    </Carousel.ItemGroup>
    <Carousel.Control class={styles.Control}>
      <Carousel.PrevTrigger class={styles.Trigger}>{'‹'}</Carousel.PrevTrigger>
      <Carousel.AutoplayTrigger class={styles.AutoplayTrigger}>
        <Carousel.AutoplayIndicator fallback="▶">{'⏸'}</Carousel.AutoplayIndicator>
      </Carousel.AutoplayTrigger>
      <Carousel.NextTrigger class={styles.Trigger}>{'›'}</Carousel.NextTrigger>
    </Carousel.Control>
  </Carousel.Root>
}

```

### Pause on Hover

This feature isn't built-in, but you can use the `play()` and `pause()` methods from `Carousel.Context` to implement
pause on hover.

**Example: pause-on-hover**

```ripple
import { Carousel } from 'ark-ripple/carousel';
import styles from 'styles/carousel.module.css';

const images = [
  { src: 'https://picsum.photos/seed/1/500/300', alt: 'Nature landscape', index: 0 },
  { src: 'https://picsum.photos/seed/2/500/300', alt: 'City skyline', index: 1 },
  { src: 'https://picsum.photos/seed/3/500/300', alt: 'Mountain view', index: 2 },
  { src: 'https://picsum.photos/seed/4/500/300', alt: 'Ocean sunset', index: 3 },
  { src: 'https://picsum.photos/seed/5/500/300', alt: 'Forest path', index: 4 },
];

export component PauseOnHover() {
  <Carousel.Root class={styles.Root} slideCount={images.length} autoplay loop>
    <Carousel.Control class={styles.Control}>
      <Carousel.Context>
        component children({ context }) {
          <span class={styles.StatusText}>
            {'Autoplay is: '}
            {@context.isPlaying ? 'playing' : 'paused'}
          </span>
        }
      </Carousel.Context>
    </Carousel.Control>
    <Carousel.Context>
      component children({ context }) {
        <Carousel.ItemGroup
          class={styles.ItemGroup}
          onPointerOver={() => {
            @context.pause();
          }}
          onPointerLeave={() => {
            @context.play();
          }}
        >
          for (const image of images; key image.index) {
            <Carousel.Item class={styles.Item} index={image.index}>
              <img src={image.src} alt={image.alt} width="500" height="300" />
            </Carousel.Item>
          }
        </Carousel.ItemGroup>
      }
    </Carousel.Context>
    <Carousel.IndicatorGroup class={styles.IndicatorGroup}>
      for (const image of images; key image.index) {
        <Carousel.Indicator class={styles.Indicator} index={image.index} />
      }
    </Carousel.IndicatorGroup>
  </Carousel.Root>
}

```

### Thumbnail Indicators

Replace default indicator dots with image thumbnails. Render each thumbnail inside `Carousel.Indicator` to create a
visual preview of each slide:

**Example: thumbnail-indicator**

```ripple
import { Carousel } from 'ark-ripple/carousel';
import styles from 'styles/carousel.module.css';

const images = [
  { src: 'https://picsum.photos/seed/1/500/300', alt: 'Nature landscape', index: 0 },
  { src: 'https://picsum.photos/seed/2/500/300', alt: 'City skyline', index: 1 },
  { src: 'https://picsum.photos/seed/3/500/300', alt: 'Mountain view', index: 2 },
  { src: 'https://picsum.photos/seed/4/500/300', alt: 'Ocean sunset', index: 3 },
  { src: 'https://picsum.photos/seed/5/500/300', alt: 'Forest path', index: 4 },
];

export component ThumbnailIndicator() {
  <Carousel.Root class={styles.Root} defaultPage={0} slideCount={images.length}>
    <Carousel.Control class={styles.Control}>
      <Carousel.PrevTrigger class={styles.Trigger}>{'←'}</Carousel.PrevTrigger>
      <Carousel.ItemGroup class={styles.ItemGroup}>
        for (const image of images; key image.index) {
          <Carousel.Item class={styles.Item} index={image.index}>
            <img src={image.src} alt={image.alt} width="500" height="300" />
          </Carousel.Item>
        }
      </Carousel.ItemGroup>
      <Carousel.NextTrigger class={styles.Trigger}>{'→'}</Carousel.NextTrigger>
    </Carousel.Control>
    <Carousel.IndicatorGroup class={styles.IndicatorGroup}>
      for (const image of images; key image.index) {
        <Carousel.Indicator class={styles.ThumbnailIndicator} index={image.index}>
          <img src={image.src} alt={image.alt} width="500" height="300" />
        </Carousel.Indicator>
      }
    </Carousel.IndicatorGroup>
  </Carousel.Root>
}

```

### Vertical

Add the `orientation="vertical"` prop to `Carousel.Root` to switch the carousel to vertical scrolling. This can be
helpful for displaying vertical galleries or content feeds.

**Example: vertical**

```ripple
import { Carousel } from 'ark-ripple/carousel';
import styles from 'styles/carousel.module.css';

const images = [
  { src: 'https://picsum.photos/seed/1/500/300', alt: 'Nature landscape', index: 0 },
  { src: 'https://picsum.photos/seed/2/500/300', alt: 'City skyline', index: 1 },
  { src: 'https://picsum.photos/seed/3/500/300', alt: 'Mountain view', index: 2 },
  { src: 'https://picsum.photos/seed/4/500/300', alt: 'Ocean sunset', index: 3 },
  { src: 'https://picsum.photos/seed/5/500/300', alt: 'Forest path', index: 4 },
];

export component Vertical() {
  <Carousel.Root
    class={styles.Root}
    defaultPage={0}
    orientation="vertical"
    slideCount={images.length}
  >
    <Carousel.ItemGroup class={styles.ItemGroup}>
      for (const image of images; key image.index) {
        <Carousel.Item class={styles.Item} index={image.index}>
          <img src={image.src} alt={image.alt} width="500" height="300" />
        </Carousel.Item>
      }
    </Carousel.ItemGroup>
    <Carousel.Control class={styles.Control}>
      <Carousel.PrevTrigger class={styles.Trigger}>{'↑'}</Carousel.PrevTrigger>
      <Carousel.IndicatorGroup class={styles.IndicatorGroup}>
        for (const image of images; key image.index) {
          <Carousel.Indicator class={styles.Indicator} index={image.index} />
        }
      </Carousel.IndicatorGroup>
      <Carousel.NextTrigger class={styles.Trigger}>{'↓'}</Carousel.NextTrigger>
    </Carousel.Control>
  </Carousel.Root>
}

```

### Dynamic

Manage slides dynamically by storing them in state and syncing the carousel page. Pass the `page` prop and
`onPageChange` handler to `Carousel.Root`, and update `slideCount` when slides are added or removed. This demonstrates
bidirectional state synchronization between your component state and the carousel.

**Example: dynamic-slides**

```ripple
import { Carousel } from 'ark-ripple/carousel';
import { track } from 'ripple';
import button from 'styles/button.module.css';
import styles from 'styles/carousel.module.css';

export component DynamicSlides() {
  let slides = track([0, 1, 2, 3, 4]);
  let page = track(0);

  <div class="stack">
    <Carousel.Root
      class={styles.Root}
      slideCount={@slides.length}
      {page}
      onPageChange={(e) => {
        @page = e.page;
      }}
    >
      <Carousel.ItemGroup class={styles.ItemGroup}>
        for (const index of @slides; key index) {
          <Carousel.Item class={styles.Item} {index}>
            <div class={styles.Slide}>
              {'Slide '}
              {index + 1}
            </div>
          </Carousel.Item>
        }
      </Carousel.ItemGroup>
      <Carousel.Control class={styles.Control}>
        <Carousel.PrevTrigger class={styles.Trigger}>{'←'}</Carousel.PrevTrigger>
        <Carousel.IndicatorGroup class={styles.IndicatorGroup}>
          for (const index of @slides; key index) {
            <Carousel.Indicator class={styles.Indicator} {index} />
          }
        </Carousel.IndicatorGroup>
        <Carousel.NextTrigger class={styles.Trigger}>{'→'}</Carousel.NextTrigger>
      </Carousel.Control>
    </Carousel.Root>
    <button
      class={button.Root}
      onClick={() => {
        @slides = [...@slides, @slides.length];
      }}
    >
      {'+ Add Slide'}
    </button>
  </div>
}

```

### Scroll to Slide

Use `Carousel.Context` to access the carousel API and call `api.scrollToIndex(index)` to programmatically navigate to a
specific slide. This is useful for creating custom navigation or jump-to-slide functionality.

**Example: scroll-to**

```ripple
import { Carousel } from 'ark-ripple/carousel';
import button from 'styles/button.module.css';
import styles from 'styles/carousel.module.css';

const slides = [0, 1, 2, 3, 4];

export component ScrollTo() {
  <Carousel.Root class={styles.Root} slideCount={slides.length}>
    <Carousel.Context>
      component children({ context }) {
        <button
          class={button.Root}
          onClick={() => {
            @context.scrollToIndex(3);
          }}
        >
          {'Go to slide 4'}
        </button>
      }
    </Carousel.Context>
    <Carousel.ItemGroup class={styles.ItemGroup}>
      for (const index of slides; key index) {
        <Carousel.Item class={styles.Item} {index}>
          <div class={styles.Slide}>
            {'Slide '}
            {index + 1}
          </div>
        </Carousel.Item>
      }
    </Carousel.ItemGroup>
    <Carousel.Control class={styles.Control}>
      <Carousel.PrevTrigger class={styles.Trigger}>{'←'}</Carousel.PrevTrigger>
      <Carousel.NextTrigger class={styles.Trigger}>{'→'}</Carousel.NextTrigger>
    </Carousel.Control>
    <Carousel.IndicatorGroup class={styles.IndicatorGroup}>
      for (const index of slides; key index) {
        <Carousel.Indicator class={styles.Indicator} {index} />
      }
    </Carousel.IndicatorGroup>
  </Carousel.Root>
}

```

### Slides Per Page

Display multiple slides simultaneously by setting the `slidesPerPage` prop on `Carousel.Root`. Use `api.pageSnapPoints`
from `Carousel.Context` to render the correct number of indicators based on pages rather than individual slides. Add the
`spacing` prop to control the gap between slides.

**Example: slides-per-page**

```ripple
import { Carousel } from 'ark-ripple/carousel';
import styles from 'styles/carousel.module.css';

const slides = [0, 1, 2, 3, 4, 5];
const pageIndicators = [0, 1, 2];

export component SlidesPerPage() {
  <Carousel.Root class={styles.Root} slideCount={slides.length} slidesPerPage={2} spacing="20px">
    <Carousel.Control class={styles.Control}>
      <Carousel.PrevTrigger class={styles.Trigger}>{'←'}</Carousel.PrevTrigger>
      <Carousel.NextTrigger class={styles.Trigger}>{'→'}</Carousel.NextTrigger>
    </Carousel.Control>
    <Carousel.ItemGroup class={styles.ItemGroup}>
      for (const index of slides; key index) {
        <Carousel.Item class={styles.Item} {index}>
          <div class={styles.Slide}>
            {'Slide '}
            {index + 1}
          </div>
        </Carousel.Item>
      }
    </Carousel.ItemGroup>
    <Carousel.IndicatorGroup class={styles.IndicatorGroup}>
      for (const index of pageIndicators; key index) {
        <Carousel.Indicator class={styles.Indicator} {index} />
      }
    </Carousel.IndicatorGroup>
  </Carousel.Root>
}

```

### Spacing

Control the gap between slides using the `spacing` prop on `Carousel.Root`. Combine it with `slidesPerPage` to create
layouts that show partial previews of adjacent slides.

**Example: spacing**

```ripple
import { Carousel } from 'ark-ripple/carousel';
import styles from 'styles/carousel.module.css';

const slides = [0, 1, 2, 3, 4, 5];

export component Spacing() {
  <Carousel.Root class={styles.Root} slideCount={slides.length} slidesPerPage={1.5} spacing="48px">
    <span class={styles.StatusText}>{'spacing=\'48px\''}</span>
    <Carousel.ItemGroup class={styles.ItemGroup}>
      for (const index of slides; key index) {
        <Carousel.Item class={styles.Item} {index}>
          <div class={styles.Slide}>{index + 1}</div>
        </Carousel.Item>
      }
    </Carousel.ItemGroup>
    <Carousel.Control class={styles.Control}>
      <Carousel.PrevTrigger class={styles.Trigger}>{'←'}</Carousel.PrevTrigger>
      <Carousel.Context>
        component children({ context }) {
          <Carousel.IndicatorGroup class={styles.IndicatorGroup}>
            for (const snapPoint of @context.pageSnapPoints; key snapPoint) {
              <Carousel.Indicator
                class={styles.Indicator}
                index={@context.pageSnapPoints.indexOf(snapPoint)}
              />
            }
          </Carousel.IndicatorGroup>
        }
      </Carousel.Context>
      <Carousel.NextTrigger class={styles.Trigger}>{'→'}</Carousel.NextTrigger>
    </Carousel.Control>
  </Carousel.Root>
}

```

### Variable Sizes

To allow slides with different widths, set the `autoSize` prop on `Carousel.Root`. This lets each `Carousel.Item` define
its own width, and the carousel will adjust automatically. You can also use the `snapAlign` prop on individual items to
control where each one snaps into view.

**Example: variable-size**

```ripple
import { Carousel } from 'ark-ripple/carousel';
import styles from 'styles/carousel.module.css';

const items = [
  { id: '1', width: '120px', label: 'Small', index: 0 },
  { id: '2', width: '200px', label: 'Medium Size', index: 1 },
  { id: '3', width: '80px', label: 'XS', index: 2 },
  { id: '4', width: '250px', label: 'Large Content Here', index: 3 },
  { id: '5', width: '150px', label: 'Regular', index: 4 },
];

export component VariableSize() {
  <Carousel.Root class={styles.Root} slideCount={items.length} autoSize spacing="8px">
    <Carousel.Control class={styles.Control}>
      <Carousel.PrevTrigger class={styles.Trigger}>{'←'}</Carousel.PrevTrigger>
      <Carousel.NextTrigger class={styles.Trigger}>{'→'}</Carousel.NextTrigger>
    </Carousel.Control>
    <Carousel.ItemGroup class={styles.ItemGroup}>
      for (const item of items; key item.id) {
        <Carousel.Item index={item.index} snapAlign="center">
          <div class={styles.Slide} style={{ width: item.width, height: '6rem' }}>{item.label}</div>
        </Carousel.Item>
      }
    </Carousel.ItemGroup>
    <Carousel.Context>
      component children({ context }) {
        <Carousel.IndicatorGroup class={styles.IndicatorGroup}>
          for (const snapPoint of @context.pageSnapPoints; key snapPoint) {
            <Carousel.Indicator
              class={styles.Indicator}
              index={@context.pageSnapPoints.indexOf(snapPoint)}
            />
          }
        </Carousel.IndicatorGroup>
      }
    </Carousel.Context>
  </Carousel.Root>
}

```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `slideCount` | `number` | Yes | The total number of slides.
Useful for SSR to render the initial ating the snap points. |
| `allowMouseDrag` | `boolean` | No | Whether to allow scrolling via dragging with mouse |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `autoplay` | `boolean | { delay: number }` | No | Whether to scroll automatically. The default delay is 4000ms. |
| `autoSize` | `boolean` | No | Whether to enable variable width slides. |
| `defaultPage` | `number` | No | The initial page to scroll to when rendered.
Use when you don't need to control the page of the carousel. |
| `ids` | `Partial<{
  root: string
  item: (index: number) => string
  itemGroup: string
  nextTrigger: string
  prevTrigger: string
  indicatorGroup: string
  indicator: (index: number) => string
}>` | No | The ids of the elements in the carousel. Useful for composition. |
| `inViewThreshold` | `number | number[]` | No | The threshold for determining if an item is in view. |
| `loop` | `boolean` | No | Whether the carousel should loop around. |
| `onAutoplayStatusChange` | `(details: AutoplayStatusDetails) => void` | No | Function called when the autoplay status changes. |
| `onDragStatusChange` | `(details: DragStatusDetails) => void` | No | Function called when the drag status changes. |
| `onPageChange` | `(details: PageChangeDetails) => void` | No | Function called when the page changes. |
| `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the element. |
| `padding` | `string` | No | Defines the extra space added around the scrollable area,
enabling nearby items to remain partially in view. |
| `page` | `number` | No | The controlled page of the carousel. |
| `slidesPerMove` | `number | 'auto'` | No | The number of slides to scroll at a time.

When set to `auto`, the number of slides to scroll is determined by the
`slidesPerPage` property. |
| `slidesPerPage` | `number` | No | The number of slides to show at a time. |
| `snapType` | `'proximity' | 'mandatory'` | No | The snap type of the item. |
| `spacing` | `string` | No | The amount of space between items. |
| `translations` | `IntlTranslations` | No | The localized messages to use. |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | carousel |
| `[data-part]` | root |
| `[data-orientation]` | The orientation of the carousel |


**Root CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--slides-per-page` | The number of slides visible per page |
| `--slide-spacing` | The spacing between slides |
| `--slide-item-size` | The calculated size of each slide item |


**AutoplayIndicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `fallback` | `string | number | bigint | boolean | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...>` | No | The fallback content to render when autoplay is paused. |


**AutoplayTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**AutoplayTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | carousel |
| `[data-part]` | autoplay-trigger |
| `[data-orientation]` | The orientation of the autoplaytrigger |
| `[data-pressed]` | Present when pressed |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | carousel |
| `[data-part]` | control |
| `[data-orientation]` | The orientation of the control |


**IndicatorGroup Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**IndicatorGroup Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | carousel |
| `[data-part]` | indicator-group |
| `[data-orientation]` | The orientation of the indicatorgroup |


**Indicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes | The index of the indicator. |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `readOnly` | `boolean` | No | Whether the indicator is read only. |


**Indicator Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | carousel |
| `[data-part]` | indicator |
| `[data-orientation]` | The orientation of the indicator |
| `[data-index]` | The index of the item |
| `[data-readonly]` | Present when read-only |
| `[data-current]` | Present when current |


**ItemGroup Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemGroup Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | carousel |
| `[data-part]` | item-group |
| `[data-orientation]` | The orientation of the item |
| `[data-dragging]` | Present when in the dragging state |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes | The index of the item. |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `snapAlign` | `'center' | 'start' | 'end'` | No | The snap alignment of the item. |


**Item Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | carousel |
| `[data-part]` | item |
| `[data-index]` | The index of the item |
| `[data-inview]` | Present when in viewport |
| `[data-orientation]` | The orientation of the item |


**NextTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**NextTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | carousel |
| `[data-part]` | next-trigger |
| `[data-orientation]` | The orientation of the nexttrigger |


**PrevTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**PrevTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | carousel |
| `[data-part]` | prev-trigger |
| `[data-orientation]` | The orientation of the prevtrigger |


**ProgressText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseCarouselReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `page` | `number` | The current index of the carousel |
| `pageSnapPoints` | `number[]` | The current snap points of the carousel |
| `isPlaying` | `boolean` | Whether the carousel is auto playing |
| `isDragging` | `boolean` | Whether the carousel is being dragged. This only works when `draggable` is true. |
| `canScrollNext` | `boolean` | Whether the carousel is can scroll to the next view |
| `canScrollPrev` | `boolean` | Whether the carousel is can scroll to the previous view |
| `scrollToIndex` | `(index: number, instant?: boolean) => void` | Function to scroll to a specific item index |
| `scrollTo` | `(page: number, instant?: boolean) => void` | Function to scroll to a specific page |
| `scrollNext` | `(instant?: boolean) => void` | Function to scroll to the next page |
| `scrollPrev` | `(instant?: boolean) => void` | Function to scroll to the previous page |
| `getProgress` | `() => number` | Returns the current scroll progress as a percentage |
| `getProgressText` | `() => string` | Returns the progress text |
| `play` | `VoidFunction` | Function to start/resume autoplay |
| `pause` | `VoidFunction` | Function to pause autoplay |
| `isInView` | `(index: number) => boolean` | Whether the item is in view |
| `refresh` | `VoidFunction` | Function to re-compute the snap points
and clamp the page |


## Accessibility

Complies with the [Carousel WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/carousel/).


# Checkbox 



## Anatomy



```tsx
<Checkbox.Root>
  <Checkbox.Control>
    <Checkbox.Indicator />
  </Checkbox.Control>
  <Checkbox.Label />
  <Checkbox.HiddenInput />
</Checkbox.Root>
```

## Examples

**Example: basic**

```ripple
import { Checkbox } from 'ark-ripple/checkbox';
import { Check } from 'lucide-ripple';
import styles from 'styles/checkbox.module.css';

export component Basic() {
  <Checkbox.Root class={styles.Root}>
    <Checkbox.Control class={styles.Control}>
      <Checkbox.Indicator class={styles.Indicator}>
        <Check />
      </Checkbox.Indicator>
    </Checkbox.Control>
    <Checkbox.Label class={styles.Label}>{'Checkbox'}</Checkbox.Label>
    <Checkbox.HiddenInput />
  </Checkbox.Root>
}

```

### Default Checked

Use the `defaultChecked` prop to set the initial checked state in an uncontrolled manner. The checkbox will manage its
own state internally.

**Example: default-checked**

```ripple
import { Checkbox } from 'ark-ripple/checkbox';
import styles from 'styles/checkbox.module.css';
import { Check } from 'lucide-ripple';

export component DefaultChecked() {
  <Checkbox.Root class={styles.Root} defaultChecked>
    <Checkbox.Control class={styles.Control}>
      <Checkbox.Indicator class={styles.Indicator}>
        <Check />
      </Checkbox.Indicator>
    </Checkbox.Control>
    <Checkbox.Label class={styles.Label}>{'Checkbox'}</Checkbox.Label>
    <Checkbox.HiddenInput />
  </Checkbox.Root>
}

```

### Controlled

Use the `checked` and `onCheckedChange` props to programatically control the checkbox's state.

**Example: controlled**

```ripple
import { Checkbox } from 'ark-ripple/checkbox';
import styles from 'styles/checkbox.module.css';
import { track } from 'ripple';
import { Check } from 'lucide-ripple';

export component Controlled() {
  let checked = track(true);

  <Checkbox.Root
    class={styles.Root}
    {checked}
    onCheckedChange={(e) => {
      @checked = e.checked;
    }}
  >
    <Checkbox.Control class={styles.Control}>
      <Checkbox.Indicator class={styles.Indicator}>
        <Check />
      </Checkbox.Indicator>
    </Checkbox.Control>
    <Checkbox.Label class={styles.Label}>{'Checkbox'}</Checkbox.Label>
    <Checkbox.HiddenInput />
  </Checkbox.Root>
}

```

### Root Provider

An alternative way to control the checkbox is to use the `RootProvider` component and the `useCheckbox` hook. This way
you can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { Checkbox, useCheckbox } from 'ark-ripple/checkbox';
import styles from 'styles/checkbox.module.css';
import button from 'styles/button.module.css';
import { Check } from 'lucide-ripple';

export component RootProvider() {
  const checkbox = useCheckbox();

  <div class="vstack">
    <Checkbox.RootProvider class={styles.Root} value={checkbox}>
      <Checkbox.Control class={styles.Control}>
        <Checkbox.Indicator class={styles.Indicator}>
          <Check />
        </Checkbox.Indicator>
      </Checkbox.Control>
      <Checkbox.Label class={styles.Label}>{'Checkbox'}</Checkbox.Label>
      <Checkbox.HiddenInput />
    </Checkbox.RootProvider>
    if (@checkbox.checked) {
      <button
        type="button"
        onClick={() => {
          @checkbox.setChecked(false);
        }}
        class={button.Root}
      >
        {'Uncheck'}
      </button>
    } else {
      <button
        type="button"
        onClick={() => {
          @checkbox.setChecked(true);
        }}
        class={button.Root}
      >
        {'Check'}
      </button>
    }
  </div>
}

```

### Disabled

Use the `disabled` prop to make the checkbox non-interactive.

**Example: disabled**

```ripple
import { Checkbox } from 'ark-ripple/checkbox';
import styles from 'styles/checkbox.module.css';
import { Check } from 'lucide-ripple';

export component Disabled() {
  <Checkbox.Root class={styles.Root} disabled>
    <Checkbox.Control class={styles.Control}>
      <Checkbox.Indicator class={styles.Indicator}>
        <Check />
      </Checkbox.Indicator>
    </Checkbox.Control>
    <Checkbox.Label class={styles.Label}>{'Checkbox'}</Checkbox.Label>
    <Checkbox.HiddenInput />
  </Checkbox.Root>
}

```

### Indeterminate

Use the `indeterminate` prop to create a checkbox in an indeterminate state (partially checked).

**Example: indeterminate**

```ripple
import { Checkbox } from 'ark-ripple/checkbox';
import styles from 'styles/checkbox.module.css';
import { Check, Minus } from 'lucide-ripple';

export component Indeterminate() {
  <Checkbox.Root class={styles.Root} checked="indeterminate">
    <Checkbox.Control class={styles.Control}>
      <Checkbox.Indicator class={styles.Indicator}>
        <Check />
      </Checkbox.Indicator>
      <Checkbox.Indicator class={styles.Indicator} indeterminate>
        <Minus />
      </Checkbox.Indicator>
    </Checkbox.Control>
    <Checkbox.Label class={styles.Label}>{'Checkbox'}</Checkbox.Label>
    <Checkbox.HiddenInput />
  </Checkbox.Root>
}

```

### Field

The checkbox integrates smoothly with the `Field` component to handle form state, helper text, and error text for proper
accessibility.

**Example: with-field**

```ripple
import { Checkbox } from 'ark-ripple/checkbox';
import { Field } from 'ark-ripple/field';
import { Check, Minus } from 'lucide-ripple';
import styles from 'styles/checkbox.module.css';
import field from 'styles/field.module.css';

export component WithField() {
  <Field.Root class={field.Root} data-inline>
    <Checkbox.Root class={styles.Root}>
      <Checkbox.Control class={styles.Control}>
        <Checkbox.Indicator class={styles.Indicator}>
          <Check />
        </Checkbox.Indicator>
        <Checkbox.Indicator class={styles.Indicator} indeterminate>
          <Minus />
        </Checkbox.Indicator>
      </Checkbox.Control>
      <Checkbox.Label class={styles.Label}>{'Label'}</Checkbox.Label>
      <Checkbox.HiddenInput />
    </Checkbox.Root>
    <Field.HelperText class={field.HelperText}>{'Additional Info'}</Field.HelperText>
    <Field.ErrorText class={field.ErrorText}>{'Error Info'}</Field.ErrorText>
  </Field.Root>
}

```

### Form

Pass the `name` and `value` props to the `Checkbox.Root` component to make the checkbox part of a form. The checkbox's
value will be submitted with the form when the user submits it.

**Example: with-form**

```ripple
import { Checkbox } from 'ark-ripple/checkbox';
import styles from 'styles/checkbox.module.css';
import button from 'styles/button.module.css';
import { Check } from 'lucide-ripple';

export component WithForm() {
  <form
    style={{ display: 'flex', flexDirection: 'column', gap: '1rem', alignItems: 'flex-start' }}
    onSubmit={(e) => {
      e.preventDefault();
      console.log('terms:', new FormData(e.currentTarget).get('terms'));
    }}
  >
    <Checkbox.Root class={styles.Root} name="terms" value="accepted">
      <Checkbox.Control class={styles.Control}>
        <Checkbox.Indicator class={styles.Indicator}>
          <Check />
        </Checkbox.Indicator>
      </Checkbox.Control>
      <Checkbox.Label class={styles.Label}>{'I agree to the terms and conditions'}</Checkbox.Label>
      <Checkbox.HiddenInput />
    </Checkbox.Root>
    <button class={button.Root} data-variant="solid" type="submit">{'Submit'}</button>
  </form>
}

```

### Context

Access the checkbox's state and methods with `Checkbox.Context` or the `useCheckboxContext` hook.

**Example: context**

```ripple
import { Checkbox } from 'ark-ripple/checkbox';
import styles from 'styles/checkbox.module.css';
import { Check } from 'lucide-ripple';

export component Context() {
  <Checkbox.Root class={styles.Root}>
    <Checkbox.Control class={styles.Control}>
      <Checkbox.Indicator class={styles.Indicator}>
        <Check />
      </Checkbox.Indicator>
    </Checkbox.Control>
    <Checkbox.Context>
      component children({ context }) {
        <Checkbox.Label class={styles.Label}>
          {'Checked: '}
          {String(@context.checked)}
        </Checkbox.Label>
      }
    </Checkbox.Context>
    <Checkbox.HiddenInput />
  </Checkbox.Root>
}

```

## Checkbox Group

Use the `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
<Checkbox.Group>
  <Checkbox.Root>
    <Checkbox.Control>
      <Checkbox.Indicator />
    </Checkbox.Control>
    <Checkbox.Label />
    <Checkbox.HiddenInput />
  </Checkbox.Root>
</Checkbox.Group>
```

**Example: group**

```ripple
import { Checkbox } from 'ark-ripple/checkbox';
import styles from 'styles/checkbox.module.css';
import { Check } from 'lucide-ripple';

export component Group() {
  <Checkbox.Group class={styles.Group} defaultValue={['react']} name="framework">
    for (const item of items; key item.value) {
      <Checkbox.Root class={styles.Root} value={item.value}>
        <Checkbox.Control class={styles.Control}>
          <Checkbox.Indicator class={styles.Indicator}>
            <Check />
          </Checkbox.Indicator>
        </Checkbox.Control>
        <Checkbox.Label class={styles.Label}>{item.label}</Checkbox.Label>
        <Checkbox.HiddenInput />
      </Checkbox.Root>
    }
  </Checkbox.Group>
}

const items = [
  { label: 'React', value: 'react' },
  { label: 'Solid', value: 'solid' },
  { label: 'Vue', value: 'vue' },
];

```

### Controlled

Use the `value` and `onValueChange` props to programmatically control the checkbox group's state. This example
demonstrates how to manage selected checkboxes in an array and display the current selection.

**Example: group-controlled**

```ripple
import { Checkbox } from 'ark-ripple/checkbox';
import styles from 'styles/checkbox.module.css';
import { track } from 'ripple';
import { Check } from 'lucide-ripple';

export component GroupControlled() {
  let value = track(['react']);

  <div class="vstack">
    <output>
      {'value: '}
      {JSON.stringify(@value)}
    </output>
    <Checkbox.Group
      class={styles.Group}
      {value}
      name="framework"
      onValueChange={(v) => {
        @value = v;
        console.log(v);
      }}
    >
      for (const item of items; key item.value) {
        <Checkbox.Root class={styles.Root} value={item.value}>
          <Checkbox.Control class={styles.Control}>
            <Checkbox.Indicator class={styles.Indicator}>
              <Check />
            </Checkbox.Indicator>
          </Checkbox.Control>
          <Checkbox.Label class={styles.Label}>{item.label}</Checkbox.Label>
          <Checkbox.HiddenInput />
        </Checkbox.Root>
      }
    </Checkbox.Group>
  </div>
}

const items = [
  { label: 'React', value: 'react' },
  { label: 'Solid', value: 'solid' },
  { label: 'Vue', value: 'vue' },
];

```

### Root Provider

Use the `useCheckboxGroup` hook to create the checkbox group store and pass it to the `Checkbox.GroupProvider`
component. This provides maximum control over the group programmatically, similar to how `RootProvider` works for
individual checkboxes.

**Example: group-provider**

```ripple
import { Checkbox, useCheckboxGroup } from 'ark-ripple/checkbox';
import styles from 'styles/checkbox.module.css';
import { Check } from 'lucide-ripple';

export component GroupProvider() {
  const group = useCheckboxGroup(
    {
      defaultValue: ['react'],
      name: 'framework',
    },
  );

  <Checkbox.GroupProvider class={styles.Group} value={group}>
    for (const item of items; key item.value) {
      <Checkbox.Root class={styles.Root} value={item.value}>
        <Checkbox.Control class={styles.Control}>
          <Checkbox.Indicator class={styles.Indicator}>
            <Check />
          </Checkbox.Indicator>
        </Checkbox.Control>
        <Checkbox.Label class={styles.Label}>{item.label}</Checkbox.Label>
        <Checkbox.HiddenInput />
      </Checkbox.Root>
    }
  </Checkbox.GroupProvider>
}

const items = [
  { label: 'React', value: 'react' },
  { label: 'Solid', value: 'solid' },
  { label: 'Vue', value: 'vue' },
];

```

### Invalid

Use the `invalid` prop on `Checkbox.Group` to mark the entire group as invalid for validation purposes. This applies the
invalid state to all checkboxes within the group.

**Example: group-with-invalid**

```ripple
import { Checkbox } from 'ark-ripple/checkbox';
import styles from 'styles/checkbox.module.css';
import { Check } from 'lucide-ripple';

export component GroupWithInvalid() {
  <Checkbox.Group class={styles.Group} invalid>
    for (const item of items; key item.value) {
      <Checkbox.Root class={styles.Root} value={item.value}>
        <Checkbox.Control class={styles.Control}>
          <Checkbox.Indicator class={styles.Indicator}>
            <Check />
          </Checkbox.Indicator>
        </Checkbox.Control>
        <Checkbox.Label class={styles.Label}>{item.label}</Checkbox.Label>
        <Checkbox.HiddenInput />
      </Checkbox.Root>
    }
  </Checkbox.Group>
}

const items = [
  { label: 'React', value: 'react' },
  { label: 'Solid', value: 'solid' },
  { label: 'Vue', value: 'vue' },
];

```

### Max Selected

Use the `maxSelectedValues` prop to limit the number of checkboxes that can be selected at once. Once the maximum is
reached, remaining checkboxes become disabled.

**Example: group-with-max-selected**

```ripple
import { Checkbox } from 'ark-ripple/checkbox';
import styles from 'styles/checkbox.module.css';
import { Check } from 'lucide-ripple';

export component GroupWithMaxSelected() {
  <Checkbox.Group
    class={styles.Group}
    defaultValue={['react']}
    maxSelectedValues={2}
    name="framework"
  >
    for (const item of items; key item.value) {
      <Checkbox.Root class={styles.Root} value={item.value}>
        <Checkbox.Control class={styles.Control}>
          <Checkbox.Indicator class={styles.Indicator}>
            <Check />
          </Checkbox.Indicator>
        </Checkbox.Control>
        <Checkbox.Label class={styles.Label}>{item.label}</Checkbox.Label>
        <Checkbox.HiddenInput />
      </Checkbox.Root>
    }
  </Checkbox.Group>
}

const items = [
  { label: 'React', value: 'react' },
  { label: 'Solid', value: 'solid' },
  { label: 'Vue', value: 'vue' },
  { label: 'Svelte', value: 'svelte' },
];

```

### Select All

Implement a "select all" checkbox that controls all checkboxes within a group. The parent checkbox automatically shows
an indeterminate state when some (but not all) items are selected, and becomes fully checked when all items are
selected.

**Example: group-with-select-all**

```ripple
import { Checkbox } from 'ark-ripple/checkbox';
import { Check, Minus } from 'lucide-ripple';
import { track, trackSplit } from 'ripple';
import styles from 'styles/checkbox.module.css';

component CheckboxItem(props: Checkbox.RootProps & { children?: any }) {
  <Checkbox.Root class={styles.Root} {...props}>
    <Checkbox.Control class={styles.Control}>
      <Checkbox.Indicator class={styles.Indicator}>
        <Check />
      </Checkbox.Indicator>
      <Checkbox.Indicator class={styles.Indicator} indeterminate>
        <Minus />
      </Checkbox.Indicator>
    </Checkbox.Control>
    <Checkbox.Label class={styles.Label}>
      <props.children />
    </Checkbox.Label>
    <Checkbox.HiddenInput />
  </Checkbox.Root>
}

export component GroupWithSelectAll() {
  let value = track<string[]>([]);

  const handleSelectAll = (checked: boolean) => {
    @value = checked ? items.map((item) => item.value) : [];
  };

  const allSelected = track(() => @value.length === items.length);
  const indeterminate = track(() => @value.length > 0 && @value.length < items.length);

  <div style={{ display: 'flex', flexDirection: 'column', gap: '10px' }}>
    <output>
      {'Selected: '}
      {JSON.stringify(@value)}
    </output>

    <CheckboxItem
      value="all"
      checked={@indeterminate ? 'indeterminate' : @allSelected}
      onCheckedChange={(e) => {
        handleSelectAll(!!e.checked);
      }}
    >
      {'JSX Frameworks'}
    </CheckboxItem>

    <Checkbox.Group
      class={styles.Group}
      style={{ marginInlineStart: '1rem' }}
      {value}
      name="framework"
      onValueChange={(v) => {
        @value = v;
      }}
    >
      for (const item of items; key item.value) {
        <CheckboxItem value={item.value}>{item.label}</CheckboxItem>
      }
    </Checkbox.Group>
  </div>
}

const items = [
  { label: 'React', value: 'react' },
  { label: 'Solid', value: 'solid' },
  { label: 'Vue', value: 'vue' },
];

```

### Form

Use the `Checkbox.Group` component within a form to handle multiple checkbox values with form submission. The `name`
prop ensures all selected values are collected as an array when the form is submitted using `FormData.getAll()`.

**Example: group-with-form**

```ripple
import { Checkbox } from 'ark-ripple/checkbox';
import styles from 'styles/checkbox.module.css';
import button from 'styles/button.module.css';
import { Check } from 'lucide-ripple';

export component GroupWithForm() {
  <form
    class="vstack"
    onSubmit={(e) => {
      e.preventDefault();
      console.log(new FormData(e.currentTarget).getAll('framework'));
    }}
  >
    <Checkbox.Group class={styles.Group} defaultValue={['react']} name="framework">
      for (const item of items; key item.value) {
        <Checkbox.Root class={styles.Root} value={item.value}>
          <Checkbox.Control class={styles.Control}>
            <Checkbox.Indicator class={styles.Indicator}>
              <Check />
            </Checkbox.Indicator>
          </Checkbox.Control>
          <Checkbox.Label class={styles.Label}>{item.label}</Checkbox.Label>
          <Checkbox.HiddenInput />
        </Checkbox.Root>
      }
    </Checkbox.Group>
    <button class={button.Root} type="submit">{'Submit'}</button>
  </form>
}

const items = [
  { label: 'React', value: 'react' },
  { label: 'Solid', value: 'solid' },
  { label: 'Vue', value: 'vue' },
];

```

### Fieldset

Use the `Fieldset` component with `Checkbox.Group` to provide semantic grouping with legend, helper text, and error text
support.

**Example: group-with-fieldset**

```ripple
import { Checkbox } from 'ark-ripple/checkbox';
import { Fieldset } from 'ark-ripple/fieldset';
import { Check } from 'lucide-ripple';
import styles from 'styles/checkbox.module.css';
import fieldset from 'styles/fieldset.module.css';

export component GroupWithFieldset() {
  <Fieldset.Root class={fieldset.Root}>
    <Fieldset.Legend class={fieldset.Legend}>{'Select frameworks'}</Fieldset.Legend>
    <Fieldset.HelperText class={fieldset.HelperText}>
      {'Choose your preferred frameworks'}
    </Fieldset.HelperText>
    <Checkbox.Group class={styles.Group} defaultValue={['react']} name="framework">
      for (const item of items; key item.value) {
        <Checkbox.Root class={styles.Root} value={item.value}>
          <Checkbox.Control class={styles.Control}>
            <Checkbox.Indicator class={styles.Indicator}>
              <Check />
            </Checkbox.Indicator>
          </Checkbox.Control>
          <Checkbox.Label class={styles.Label}>{item.label}</Checkbox.Label>
          <Checkbox.HiddenInput />
        </Checkbox.Root>
      }
    </Checkbox.Group>
  </Fieldset.Root>
}

const items = [
  { label: 'React', value: 'react' },
  { label: 'Solid', value: 'solid' },
  { label: 'Vue', value: 'vue' },
];

```

## Guides

### asChild Behavior

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.

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `checked` | `CheckedState` | No | The controlled checked state of the checkbox |
| `defaultChecked` | `CheckedState` | No | The initial checked state of the checkbox when rendered.
Use when you don't need to control the checked state of the checkbox. |
| `disabled` | `boolean` | No | Whether the checkbox is disabled |
| `form` | `string` | No | The id of the form that the checkbox belongs to. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{ root: string; hiddenInput: string; control: string; label: string }>` | No | The ids of the elements in the checkbox. Useful for composition. |
| `invalid` | `boolean` | No | Whether the checkbox is invalid |
| `name` | `string` | No | The name of the input field in a checkbox.
Useful for form submission. |
| `onCheckedChange` | `(details: CheckedChangeDetails) => void` | No | The callback invoked when the checked state changes. |
| `readOnly` | `boolean` | No | Whether the checkbox is read-only |
| `required` | `boolean` | No | Whether the checkbox is required |
| `value` | `string` | No | The value of checkbox input. Useful for form submission. |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-active]` | Present when active or pressed |
| `[data-focus]` | Present when focused |
| `[data-focus-visible]` | Present when focused with keyboard |
| `[data-readonly]` | Present when read-only |
| `[data-hover]` | Present when hovered |
| `[data-disabled]` | Present when disabled |
| `[data-state]` | "indeterminate" | "checked" | "unchecked" |
| `[data-invalid]` | Present when invalid |
| `[data-required]` | Present when required |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-active]` | Present when active or pressed |
| `[data-focus]` | Present when focused |
| `[data-focus-visible]` | Present when focused with keyboard |
| `[data-readonly]` | Present when read-only |
| `[data-hover]` | Present when hovered |
| `[data-disabled]` | Present when disabled |
| `[data-state]` | "indeterminate" | "checked" | "unchecked" |
| `[data-invalid]` | Present when invalid |
| `[data-required]` | Present when required |


**Group Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `defaultValue` | `string[]` | No | The initial value of `value` when uncontrolled |
| `disabled` | `boolean` | No | If `true`, the checkbox group is disabled |
| `invalid` | `boolean` | No | If `true`, the checkbox group is invalid |
| `maxSelectedValues` | `number` | No | The maximum number of selected values |
| `name` | `string` | No | The name of the input fields in the checkbox group
(Useful for form submission). |
| `onValueChange` | `(value: string[]) => void` | No | The callback to call when the value changes |
| `readOnly` | `boolean` | No | If `true`, the checkbox group is read-only |
| `value` | `string[]` | No | The controlled value of the checkbox group |


**GroupProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseCheckboxGroupContext` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**HiddenInput Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Indicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `indeterminate` | `boolean` | No |  |


**Indicator Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-active]` | Present when active or pressed |
| `[data-focus]` | Present when focused |
| `[data-focus-visible]` | Present when focused with keyboard |
| `[data-readonly]` | Present when read-only |
| `[data-hover]` | Present when hovered |
| `[data-disabled]` | Present when disabled |
| `[data-state]` | "indeterminate" | "checked" | "unchecked" |
| `[data-invalid]` | Present when invalid |
| `[data-required]` | Present when required |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-active]` | Present when active or pressed |
| `[data-focus]` | Present when focused |
| `[data-focus-visible]` | Present when focused with keyboard |
| `[data-readonly]` | Present when read-only |
| `[data-hover]` | Present when hovered |
| `[data-disabled]` | Present when disabled |
| `[data-state]` | "indeterminate" | "checked" | "unchecked" |
| `[data-invalid]` | Present when invalid |
| `[data-required]` | Present when required |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseCheckboxReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `checked` | `boolean` | Whether the checkbox is checked |
| `disabled` | `boolean` | Whether the checkbox is disabled |
| `indeterminate` | `boolean` | Whether the checkbox is indeterminate |
| `focused` | `boolean` | Whether the checkbox is focused |
| `checkedState` | `CheckedState` | The checked state of the checkbox |
| `setChecked` | `(checked: CheckedState) => void` | Function to set the checked state of the checkbox |
| `toggleChecked` | `VoidFunction` | Function to toggle the checked state of the checkbox |


## Accessibility

Complies with the [Checkbox WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/).

### Keyboard Support

**`Space`**
Description: Toggle the checkbox


# Clipboard 



## Anatomy



```tsx
<Clipboard.Root>
  <Clipboard.Label />
  <Clipboard.Control>
    <Clipboard.Input />
    <Clipboard.Trigger>
      <Clipboard.Indicator />
    </Clipboard.Trigger>
  </Clipboard.Control>
</Clipboard.Root>
```

## Examples

**Example: basic**

```ripple
import { Clipboard } from 'ark-ripple/clipboard';
import { Check, Copy } from 'lucide-ripple';
import styles from 'styles/clipboard.module.css';

export component Basic() {
  <Clipboard.Root class={styles.Root} value="https://ark-ui.rip">
    <Clipboard.Label class={styles.Label}>{'Copy this link'}</Clipboard.Label>
    <Clipboard.Control class={styles.Control}>
      <Clipboard.Input class={styles.Input} />
      <Clipboard.Trigger class={styles.Trigger}>
        <Clipboard.Indicator class={styles.Indicator} copied={Check}>
          <Copy />
        </Clipboard.Indicator>
      </Clipboard.Trigger>
    </Clipboard.Control>
  </Clipboard.Root>
}

```

### Controlled

Control the clipboard value externally by managing the state yourself and using `onValueChange` to handle updates.

**Example: controlled**

```ripple
import { Clipboard } from 'ark-ripple/clipboard';
import { track } from 'ripple';
import styles from 'styles/clipboard.module.css';
import button from 'styles/button.module.css';
import { Check, Copy } from 'lucide-ripple';

export component Controlled() {
  const url = track('https://ark-ui.rip');

  <div class="stack">
    <Clipboard.Root
      class={styles.Root}
      value={@url}
      onValueChange={(details) => {
        @url = details.value;
      }}
    >
      <Clipboard.Label class={styles.Label}>{'Copy this link'}</Clipboard.Label>
      <Clipboard.Control class={styles.Control}>
        <Clipboard.Input class={styles.Input} />
        <Clipboard.Trigger class={styles.Trigger}>
          <Clipboard.Indicator class={styles.Indicator} copied={Check}>
            <Copy />
          </Clipboard.Indicator>
        </Clipboard.Trigger>
      </Clipboard.Control>
    </Clipboard.Root>
    <button
      class={button.Root}
      onClick={() => {
        @url = 'https://chakra-ui.com';
      }}
    >
      {'Change Url'}
    </button>
  </div>
}

```

### Root Provider

An alternative way to control the clipboard is to use the `RootProvider` component and the `useClipboard` hook. This way
you can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { Clipboard, useClipboard } from 'ark-ripple/clipboard';
import styles from 'styles/clipboard.module.css';
import { Check, Copy } from 'lucide-ripple';

export component RootProvider() {
  const clipboard = useClipboard({ value: 'https://ark-ui.rip' });

  <div class="stack">
    <output>
      {'value: '}
      {@clipboard.value}
      {', copied: '}
      {String(@clipboard.copied)}
    </output>
    <Clipboard.RootProvider class={styles.Root} value={clipboard}>
      <Clipboard.Label class={styles.Label}>{'Copy this link'}</Clipboard.Label>
      <Clipboard.Control class={styles.Control}>
        <Clipboard.Input class={styles.Input} />
        <Clipboard.Trigger class={styles.Trigger}>
          <Clipboard.Indicator class={styles.Indicator} copied={Check}>
            <Copy />
          </Clipboard.Indicator>
        </Clipboard.Trigger>
      </Clipboard.Control>
    </Clipboard.RootProvider>
  </div>
}

```

### Context

Access the clipboard's state with `Clipboard.Context` or the `useClipboardContext` hook. You get properties like
`copied`, `value`, and `setValue`.

> Alternatively, you can use the `useClipboardContext` hook to access the clipboard context.

**Example: context**

```ripple
import { Clipboard } from 'ark-ripple/clipboard';
import { Check, Copy } from 'lucide-ripple';
import styles from 'styles/clipboard.module.css';
import button from 'styles/button.module.css';

export component Context() {
  <Clipboard.Root class={styles.Root} value="https://ark-ui.rip">
    <Clipboard.Label class={styles.Label}>{'Copy this link'}</Clipboard.Label>
    <Clipboard.Context>
      component children({ context }) {
        <button class={button.Root} onClick={() => @context.copy()}>
          if (@context.copied) {
            <Check />
          } else {
            <Copy />
          }
          {@context.copied ? 'Copied!' : 'Copy'}
        </button>
      }
    </Clipboard.Context>
  </Clipboard.Root>
}

```

### Copy Status

Use the `onStatusChange` prop to listen for copy operations. It exposes a `copied` property that you can use to display
a success message.

**Example: copy-status**

```ripple
import { Clipboard } from 'ark-ripple/clipboard';
import { track } from 'ripple';
import { Check, Copy } from 'lucide-ripple';
import styles from 'styles/clipboard.module.css';

export component CopyStatus() {
  const copyCount = track(0);

  <Clipboard.Root
    class={styles.Root}
    value="https://ark-ui.rip"
    onStatusChange={(details) => {
      if (details.copied) {
        @copyCount = @copyCount + 1;
      }
    }}
  >
    <Clipboard.Control class={styles.Control}>
      <Clipboard.Trigger class={styles.Trigger}>
        <Clipboard.Indicator class={styles.Indicator} copied={Check}>
          <Copy />
        </Clipboard.Indicator>
        <Clipboard.ValueText />
      </Clipboard.Trigger>
    </Clipboard.Control>
    <p>
      {'Copied '}
      {@copyCount}
      {' times'}
    </p>
  </Clipboard.Root>
}

```

### Timeout

Configure the copy status timeout duration using the `timeout` prop. Default is 3000ms (3 seconds).

**Example: timeout**

```ripple
import { Clipboard } from 'ark-ripple/clipboard';
import { Check, Copy } from 'lucide-ripple';
import styles from 'styles/clipboard.module.css';

export component Timeout() {
  <Clipboard.Root class={styles.Root} value="https://ark-ui.rip" timeout={5000}>
    <Clipboard.Label class={styles.Label}>{'Copy this link (5 second timeout)'}</Clipboard.Label>
    <Clipboard.Control class={styles.Control}>
      <Clipboard.Input class={styles.Input} />
      <Clipboard.Trigger class={styles.Trigger}>
        <Clipboard.Indicator class={styles.Indicator} copied={Check}>
          <Copy />
        </Clipboard.Indicator>
      </Clipboard.Trigger>
    </Clipboard.Control>
  </Clipboard.Root>
}

```

### Value Text

Use `Clipboard.ValueText` to display the current clipboard value.

**Example: value-text**

```ripple
import { Clipboard } from 'ark-ripple/clipboard';
import { Check, Copy } from 'lucide-ripple';
import styles from 'styles/clipboard.module.css';

export component ValueText() {
  <Clipboard.Root class={styles.Root} value="https://ark-ui.rip">
    <Clipboard.Control class={styles.Control}>
      <Clipboard.ValueText class={styles.ValueText} />
      <Clipboard.Trigger class={styles.Trigger}>
        <Clipboard.Indicator class={styles.Indicator} copied={Check}>
          <Copy />
        </Clipboard.Indicator>
      </Clipboard.Trigger>
    </Clipboard.Control>
  </Clipboard.Root>
}

```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `defaultValue` | `string` | No | The initial value to be copied to the clipboard when rendered.
Use when you don't need to control the value of the clipboard. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{ root: string; input: string; label: string }>` | No | The ids of the elements in the clipboard. Useful for composition. |
| `onStatusChange` | `(details: CopyStatusDetails) => void` | No | The function to be called when the value is copied to the clipboard |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | The function to be called when the value changes |
| `timeout` | `number` | No | The timeout for the copy operation |
| `value` | `string` | No | The controlled value of the clipboard |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | clipboard |
| `[data-part]` | root |
| `[data-copied]` | Present when copied state is true |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | clipboard |
| `[data-part]` | control |
| `[data-copied]` | Present when copied state is true |


**Indicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `copied` | `string | number | bigint | boolean | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...>` | No |  |


**Input Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Input Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | clipboard |
| `[data-part]` | input |
| `[data-copied]` | Present when copied state is true |
| `[data-readonly]` | Present when read-only |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | clipboard |
| `[data-part]` | label |
| `[data-copied]` | Present when copied state is true |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseClipboardReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | clipboard |
| `[data-part]` | trigger |
| `[data-copied]` | Present when copied state is true |


**ValueText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `copied` | `boolean` | Whether the value has been copied to the clipboard |
| `value` | `string` | The value to be copied to the clipboard |
| `setValue` | `(value: string) => void` | Set the value to be copied to the clipboard |
| `copy` | `VoidFunction` | Copy the value to the clipboard |



# Collapsible 



## Anatomy



```tsx
<Collapsible.Root>
  <Collapsible.Trigger>
    <Collapsible.Indicator />
  </Collapsible.Trigger>
  <Collapsible.Content />
</Collapsible.Root>
```

## Examples

**Example: basic**

```ripple
import { Collapsible } from 'ark-ripple/collapsible';
import { ChevronRight } from 'lucide-ripple';
import styles from 'styles/collapsible.module.css';

export component Basic() {
  <Collapsible.Root class={styles.Root}>
    <Collapsible.Trigger class={styles.Trigger}>
      {'What is Ark UI?'}
      <Collapsible.Indicator class={styles.Indicator}>
        <ChevronRight />
      </Collapsible.Indicator>
    </Collapsible.Trigger>
    <Collapsible.Content class={styles.Content}>
      <div class={styles.Body}>
        {'Ark UI is a headless component library for building accessible, high-quality UI components for React, Solid, Vue, and Svelte.'}
      </div>
    </Collapsible.Content>
  </Collapsible.Root>
}

```

### Disabled

Use the `disabled` prop to disable the collapsible and prevent it from being toggled.

**Example: disabled**

```ripple
import { Collapsible } from 'ark-ripple/collapsible';
import { ChevronRight } from 'lucide-ripple';
import styles from 'styles/collapsible.module.css';

export component Disabled() {
  <Collapsible.Root class={styles.Root} disabled>
    <Collapsible.Trigger class={styles.Trigger}>
      {'System Requirements'}
      <Collapsible.Indicator class={styles.Indicator}>
        <ChevronRight />
      </Collapsible.Indicator>
    </Collapsible.Trigger>
    <Collapsible.Content class={styles.Content}>
      <div class={styles.Body}>{'This section is currently unavailable.'}</div>
    </Collapsible.Content>
  </Collapsible.Root>
}

```

### Partial Collapse

Use the `collapsedHeight` or `collapsedWidth` props to create a "show more/less" pattern. When set, the content
maintains the specified dimensions when collapsed instead of collapsing to 0px.

We expose the `--collapsed-height` or `--collapsed-width` variables to use in your CSS animations.

**Example: partial-collapse**

```ripple
import { Collapsible } from 'ark-ripple/collapsible';
import { ChevronRight } from 'lucide-ripple';
import styles from 'styles/collapsible.module.css';

export component PartialCollapse() {
  <Collapsible.Root class={styles.Root} collapsedHeight="100px">
    <Collapsible.Trigger class={styles.Trigger}>
      {'Read More'}
      <Collapsible.Indicator class={styles.Indicator}>
        <ChevronRight />
      </Collapsible.Indicator>
    </Collapsible.Trigger>
    <Collapsible.Content class={styles.Content}>
      <div class={styles.Body}>
        <p>
          {'Ark UI is a headless component library for building accessible, high-quality UI components for React, Solid, Vue, and Svelte. It provides unstyled, fully accessible components that you can customize to match your design system.'}
        </p>
        <p>
          {'Built on top of Zag.js state machines, Ark UI ensures consistent behavior across all frameworks while giving you complete control over styling. Each component follows WAI-ARIA patterns for accessibility out of the box.'}
        </p>
        <p>
          {'Whether you\'re building a design system from scratch or need reliable primitives for your next project, Ark UI provides the foundation you need without imposing any visual constraints.'}
        </p>
      </div>
    </Collapsible.Content>
  </Collapsible.Root>
}

```

> Interactive elements (links, buttons, inputs) within the collapsed area automatically become `inert` to prevent
> keyboard navigation to hidden content.

### Nested Collapsibles

You can nest collapsibles within collapsibles to create hierarchical content structures.

**Example: nested**

```ripple
import { Collapsible } from 'ark-ripple/collapsible';
import { ChevronRight } from 'lucide-ripple';
import styles from 'styles/collapsible.module.css';

export component Nested() {
  <Collapsible.Root class={styles.Root}>
    <Collapsible.Trigger class={styles.Trigger}>
      {'Getting Started'}
      <Collapsible.Indicator class={styles.Indicator}>
        <ChevronRight />
      </Collapsible.Indicator>
    </Collapsible.Trigger>
    <Collapsible.Content class={styles.Content}>
      <div class={styles.Body}>
        <p>{'Welcome to the Ark UI documentation. Here are some topics to explore:'}</p>

        <Collapsible.Root class={styles.Nested}>
          <Collapsible.Trigger class={styles.Trigger}>
            {'Installation'}
            <Collapsible.Indicator class={styles.Indicator}>
              <ChevronRight />
            </Collapsible.Indicator>
          </Collapsible.Trigger>
          <Collapsible.Content class={styles.Content}>
            <div class={styles.Body}>
              <p>{'Install Ark UI using your preferred package manager:'}</p>
              <code>{'npm install ark-ripple'}</code>
            </div>
          </Collapsible.Content>
        </Collapsible.Root>

        <Collapsible.Root class={styles.Nested}>
          <Collapsible.Trigger class={styles.Trigger}>
            {'Styling'}
            <Collapsible.Indicator class={styles.Indicator}>
              <ChevronRight />
            </Collapsible.Indicator>
          </Collapsible.Trigger>
          <Collapsible.Content class={styles.Content}>
            <div class={styles.Body}>
              <p>
                {'Ark UI components are unstyled by default. Use CSS modules, Tailwind, or any styling solution.'}
              </p>
            </div>
          </Collapsible.Content>
        </Collapsible.Root>
      </div>
    </Collapsible.Content>
  </Collapsible.Root>
}

```

### Lazy Mount

Use `lazyMount` to delay mounting the content until first opened, and `unmountOnExit` to remove it from the DOM when
collapsed. Combining both ensures the component is only in the DOM while expanded.

**Example: lazy-mount**

```ripple
import { Collapsible } from 'ark-ripple/collapsible';
import { ChevronRight } from 'lucide-ripple';
import styles from 'styles/collapsible.module.css';

export component LazyMount() {
  <Collapsible.Root class={styles.Root} lazyMount unmountOnExit>
    <Collapsible.Trigger class={styles.Trigger}>
      {'Session Details'}
      <Collapsible.Indicator class={styles.Indicator}>
        <ChevronRight />
      </Collapsible.Indicator>
    </Collapsible.Trigger>
    <Collapsible.Content class={styles.Content}>
      <div class={styles.Body}>
        {'This content is lazily mounted when first opened and removed from the DOM when collapsed.'}
      </div>
    </Collapsible.Content>
  </Collapsible.Root>
}

```

### Root Provider

An alternative way to control the collapsible is to use the `RootProvider` component and the `useCollapsible` hook. This
way you can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { Collapsible } from 'ark-ripple/collapsible';
import { useCollapsible } from 'ark-ripple/collapsible';
import { ChevronRight } from 'lucide-ripple';
import styles from 'styles/collapsible.module.css';

export component RootProvider() {
  const collapsible = useCollapsible();

  <div class="stack">
    <output>
      {'collapsible: '}
      {String(@collapsible.open)}
      {', visible: '}
      {String(@collapsible.visible)}
    </output>
    <Collapsible.RootProvider class={styles.Root} value={collapsible}>
      <Collapsible.Trigger class={styles.Trigger}>
        {'Toggle Panel'}
        <Collapsible.Indicator class={styles.Indicator}>
          <ChevronRight />
        </Collapsible.Indicator>
      </Collapsible.Trigger>
      <Collapsible.Content class={styles.Content}>
        <div class={styles.Body}>
          {'This panel can be toggled by the button above, which uses the useCollapsible hook for state management.'}
        </div>
      </Collapsible.Content>
    </Collapsible.RootProvider>
  </div>
}

```

## Guides

### Indicator Animation

To rotate the indicator icon (such as a chevron) when the collapsible opens and closes, use CSS transforms with the
`data-state` attribute:

```css
[data-scope='collapsible'][data-part='indicator'] {
  transition: transform 200ms;

  &[data-state='open'] {
    transform: rotate(180deg);
  }
}
```

### Open vs Visible

When using `useCollapsible` or `useCollapsibleContext`, you can access the `open` and `visible` state properties. They
seem similar but serve different purposes:

- **`open`**: Indicates the intended state of the collapsible. This is `true` when the collapsible should be expanded
  and `false` when it should be collapsed. This changes immediately when triggered.

- **`visible`**: Indicates whether the content is currently visible in the DOM. This accounts for exit animations - the
  content remains `visible` while the closing animation plays, even though `open` is already `false`. Once the animation
  completes, `visible` becomes `false`.

### Content Animation

Use the `--height` and/or `--width` CSS variables to animate the size of the content when it expands or closes.

If you use `collapsedHeight` or `collapsedWidth`, update your CSS animations to use the `--collapsed-height` or
`--collapsed-width` variables as the starting/ending point:

```css
@keyframes expand {
  from {
    height: var(--collapsed-height, 0);
  }
  to {
    height: var(--height);
  }
}

@keyframes collapse {
  from {
    height: var(--height);
  }
  to {
    height: var(--collapsed-height, 0);
  }
}

[data-scope='collapsible'][data-part='content'] {
  &[data-state='open'] {
    animation: expand 250ms;
  }
  &[data-state='closed'] {
    animation: collapse 250ms;
  }
}
```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `collapsedHeight` | `string | number` | No | The height of the content when collapsed. |
| `collapsedWidth` | `string | number` | No | The width of the content when collapsed. |
| `defaultOpen` | `boolean` | No | The initial open state of the collapsible when rendered.
Use when you don't need to control the open state of the collapsible. |
| `disabled` | `boolean` | No | Whether the collapsible is disabled. |
| `ids` | `Partial<{ root: string; content: string; trigger: string }>` | No | The ids of the elements in the collapsible. Useful for composition. |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `onExitComplete` | `VoidFunction` | No | The callback invoked when the exit animation completes. |
| `onOpenChange` | `(details: OpenChangeDetails) => void` | No | The callback invoked when the open state changes. |
| `open` | `boolean` | No | The controlled open state of the collapsible. |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | collapsible |
| `[data-part]` | root |
| `[data-state]` | "open" | "closed" |


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | collapsible |
| `[data-part]` | content |
| `[data-collapsible]` |  |
| `[data-state]` | "open" | "closed" |
| `[data-disabled]` | Present when disabled |
| `[data-has-collapsed-size]` | Present when the content has collapsed width or height |


**Content CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--height` | The height of the element |
| `--width` | The width of the element |
| `--collapsed-height` | The height of the Content |
| `--collapsed-width` | The width of the Content |


**Indicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Indicator Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | collapsible |
| `[data-part]` | indicator |
| `[data-state]` | "open" | "closed" |
| `[data-disabled]` | Present when disabled |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseCollapsibleReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | collapsible |
| `[data-part]` | trigger |
| `[data-state]` | "open" | "closed" |
| `[data-disabled]` | Present when disabled |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `open` | `boolean` | Whether the collapsible is open. |
| `visible` | `boolean` | Whether the collapsible is visible (open or closing) |
| `disabled` | `boolean` | Whether the collapsible is disabled |
| `setOpen` | `(open: boolean) => void` | Function to open or close the collapsible. |
| `measureSize` | `VoidFunction` | Function to measure the size of the content. |


## Accessibility

### Keyboard Support

**`Space`**
Description: Opens/closes the collapsible.

**`Enter`**
Description: Opens/closes the collapsible.


# Color Picker 



## Anatomy



```tsx
<ColorPicker.Root>
  <ColorPicker.Label />
  <ColorPicker.Control>
    <ColorPicker.ChannelInput />
    <ColorPicker.Trigger>
      <ColorPicker.ValueSwatch />
    </ColorPicker.Trigger>
  </ColorPicker.Control>
  <ColorPicker.Positioner>
    <ColorPicker.Content>
      <ColorPicker.Area>
        <ColorPicker.AreaBackground />
        <ColorPicker.AreaThumb />
      </ColorPicker.Area>
      <ColorPicker.EyeDropperTrigger />
      <ColorPicker.ChannelSlider>
        <ColorPicker.ChannelSliderTrack />
        <ColorPicker.ChannelSliderThumb />
      </ColorPicker.ChannelSlider>
      <ColorPicker.SwatchGroup>
        <ColorPicker.SwatchTrigger>
          <ColorPicker.Swatch />
        </ColorPicker.SwatchTrigger>
      </ColorPicker.SwatchGroup>
    </ColorPicker.Content>
  </ColorPicker.Positioner>
  <ColorPicker.HiddenInput />
</ColorPicker.Root>
```

## Examples

**Example: basic**

```ripple
import { ColorPicker, parseColor } from 'ark-ripple/color-picker';
import { Pipette } from 'lucide-ripple';
import styles from 'styles/color-picker.module.css';

export component Basic() {
  <ColorPicker.Root class={styles.Root} defaultValue={parseColor('#eb5e41')}>
    <ColorPicker.Label class={styles.Label}>{'Color'}</ColorPicker.Label>
    <ColorPicker.Control class={styles.Control}>
      <ColorPicker.ChannelInput class={styles.Input} channel="hex" />
      <ColorPicker.ChannelInput class={styles.ChannelInput} channel="alpha" />
      <ColorPicker.Trigger class={styles.Trigger}>
        <div class={styles.Swatch}>
          <ColorPicker.TransparencyGrid class={styles.TransparencyGrid} />
          <ColorPicker.ValueSwatch class={styles.ValueSwatch} />
        </div>
      </ColorPicker.Trigger>
    </ColorPicker.Control>
    <ColorPicker.Positioner>
      <ColorPicker.Content class={styles.Content}>
        <ColorPicker.Area class={styles.Area}>
          <ColorPicker.AreaBackground class={styles.AreaBackground} />
          <ColorPicker.AreaThumb class={styles.AreaThumb} />
        </ColorPicker.Area>
        <div class={styles.SliderGroup}>
          <ColorPicker.EyeDropperTrigger class={styles.EyeDropperTrigger}>
            <Pipette />
          </ColorPicker.EyeDropperTrigger>
          <div class={styles.ChannelSliders}>
            <ColorPicker.ChannelSlider class={styles.ChannelSlider} channel="hue">
              <ColorPicker.ChannelSliderTrack class={styles.ChannelSliderTrack} />
              <ColorPicker.ChannelSliderThumb class={styles.ChannelSliderThumb} />
            </ColorPicker.ChannelSlider>
            <ColorPicker.ChannelSlider class={styles.ChannelSlider} channel="alpha">
              <ColorPicker.TransparencyGrid class={styles.TransparencyGrid} />
              <ColorPicker.ChannelSliderTrack class={styles.ChannelSliderTrack} />
              <ColorPicker.ChannelSliderThumb class={styles.ChannelSliderThumb} />
            </ColorPicker.ChannelSlider>
          </div>
        </div>
      </ColorPicker.Content>
    </ColorPicker.Positioner>
    <ColorPicker.HiddenInput />
  </ColorPicker.Root>
}

```

### Controlled

Use the `value` and `onValueChange` props to programatically control the color picker's state.

**Example: controlled**

```ripple
import { ColorPicker, parseColor } from 'ark-ripple/color-picker';
import { Pipette } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/color-picker.module.css';

export component Controlled() {
  let color = track(parseColor('hsl(20, 100%, 50%)'));

  <div class="stack">
    <output>
      {'Selected color: '}
      {@color.toString('hex')}
    </output>
    <ColorPicker.Root
      class={styles.Root}
      value={color}
      onValueChange={(e) => {
        @color = e.value;
      }}
    >
      <ColorPicker.Label class={styles.Label}>{'Color'}</ColorPicker.Label>
      <ColorPicker.Control class={styles.Control}>
        <ColorPicker.ChannelInput class={styles.Input} channel="hex" />
        <ColorPicker.ChannelInput class={styles.ChannelInput} channel="alpha" />
        <ColorPicker.Trigger class={styles.Trigger}>
          <div class={styles.Swatch}>
            <ColorPicker.TransparencyGrid class={styles.TransparencyGrid} />
            <ColorPicker.ValueSwatch class={styles.ValueSwatch} />
          </div>
        </ColorPicker.Trigger>
      </ColorPicker.Control>
      <ColorPicker.Positioner>
        <ColorPicker.Content class={styles.Content}>
          <ColorPicker.Area class={styles.Area}>
            <ColorPicker.AreaBackground class={styles.AreaBackground} />
            <ColorPicker.AreaThumb class={styles.AreaThumb} />
          </ColorPicker.Area>
          <div class={styles.SliderGroup}>
            <ColorPicker.EyeDropperTrigger class={styles.EyeDropperTrigger}>
              <Pipette />
            </ColorPicker.EyeDropperTrigger>
            <div class={styles.ChannelSliders}>
              <ColorPicker.ChannelSlider class={styles.ChannelSlider} channel="hue">
                <ColorPicker.ChannelSliderTrack class={styles.ChannelSliderTrack} />
                <ColorPicker.ChannelSliderThumb class={styles.ChannelSliderThumb} />
              </ColorPicker.ChannelSlider>
              <ColorPicker.ChannelSlider class={styles.ChannelSlider} channel="alpha">
                <ColorPicker.TransparencyGrid class={styles.TransparencyGrid} />
                <ColorPicker.ChannelSliderTrack class={styles.ChannelSliderTrack} />
                <ColorPicker.ChannelSliderThumb class={styles.ChannelSliderThumb} />
              </ColorPicker.ChannelSlider>
            </div>
          </div>
        </ColorPicker.Content>
      </ColorPicker.Positioner>
      <ColorPicker.HiddenInput />
    </ColorPicker.Root>
  </div>
}

```

### Open Controlled

Control the open state of the color picker popover programmatically using the `open` and `onOpenChange` props.

**Example: open-controlled**

```ripple
import { ColorPicker, parseColor } from 'ark-ripple/color-picker';
import { Pipette } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/color-picker.module.css';
import button from 'styles/button.module.css';

export component OpenControlled() {
  let open = track(false);

  <div class="stack">
    <button
      class={button.Root}
      onClick={() => {
        @open = !@open;
      }}
    >
      {'Toggle'}
    </button>
    <ColorPicker.Root
      class={styles.Root}
      {open}
      onOpenChange={(e) => {
        @open = e.open;
      }}
      defaultValue={parseColor('#eb5e41')}
    >
      <ColorPicker.Label class={styles.Label}>{'Color'}</ColorPicker.Label>
      <ColorPicker.Control class={styles.Control}>
        <ColorPicker.ChannelInput class={styles.Input} channel="hex" />
        <ColorPicker.Trigger class={styles.Trigger}>
          <div class={styles.Swatch}>
            <ColorPicker.TransparencyGrid class={styles.TransparencyGrid} />
            <ColorPicker.ValueSwatch class={styles.ValueSwatch} />
          </div>
        </ColorPicker.Trigger>
      </ColorPicker.Control>
      <ColorPicker.Positioner>
        <ColorPicker.Content class={styles.Content}>
          <ColorPicker.Area class={styles.Area}>
            <ColorPicker.AreaBackground class={styles.AreaBackground} />
            <ColorPicker.AreaThumb class={styles.AreaThumb} />
          </ColorPicker.Area>
          <div class={styles.SliderGroup}>
            <ColorPicker.EyeDropperTrigger class={styles.EyeDropperTrigger}>
              <Pipette />
            </ColorPicker.EyeDropperTrigger>
            <div class={styles.ChannelSliders}>
              <ColorPicker.ChannelSlider class={styles.ChannelSlider} channel="hue">
                <ColorPicker.ChannelSliderTrack class={styles.ChannelSliderTrack} />
                <ColorPicker.ChannelSliderThumb class={styles.ChannelSliderThumb} />
              </ColorPicker.ChannelSlider>
              <ColorPicker.ChannelSlider class={styles.ChannelSlider} channel="alpha">
                <ColorPicker.TransparencyGrid class={styles.TransparencyGrid} />
                <ColorPicker.ChannelSliderTrack class={styles.ChannelSliderTrack} />
                <ColorPicker.ChannelSliderThumb class={styles.ChannelSliderThumb} />
              </ColorPicker.ChannelSlider>
            </div>
          </div>
        </ColorPicker.Content>
      </ColorPicker.Positioner>
      <ColorPicker.HiddenInput />
    </ColorPicker.Root>
  </div>
}

```

### Root Provider

An alternative way to control the color picker is to use the `RootProvider` component and the `useColorPicker` hook.
This way you can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { ColorPicker, parseColor, useColorPicker } from 'ark-ripple/color-picker';
import { Check, Pipette } from 'lucide-ripple';
import styles from 'styles/color-picker.module.css';

const swatches = ['red', 'blue', 'green', 'orange'];

export component RootProvider() {
  const colorPicker = useColorPicker({ defaultValue: parseColor('#eb5e41') });

  <div class="stack">
    <output>
      {'Color: '}
      {@colorPicker.valueAsString}
    </output>

    <ColorPicker.RootProvider class={styles.Root} value={colorPicker}>
      <ColorPicker.Label class={styles.Label}>{'Color'}</ColorPicker.Label>
      <ColorPicker.Control class={styles.Control}>
        <ColorPicker.ChannelInput class={styles.Input} channel="hex" />
        <ColorPicker.ChannelInput class={styles.ChannelInput} channel="alpha" />
        <ColorPicker.Trigger class={styles.Trigger}>
          <div class={styles.Swatch}>
            <ColorPicker.TransparencyGrid class={styles.TransparencyGrid} />
            <ColorPicker.ValueSwatch class={styles.ValueSwatch} />
          </div>
        </ColorPicker.Trigger>
      </ColorPicker.Control>
      <ColorPicker.Positioner>
        <ColorPicker.Content class={styles.Content}>
          <ColorPicker.Area class={styles.Area}>
            <ColorPicker.AreaBackground class={styles.AreaBackground} />
            <ColorPicker.AreaThumb class={styles.AreaThumb} />
          </ColorPicker.Area>
          <div class={styles.SliderGroup}>
            <ColorPicker.EyeDropperTrigger class={styles.EyeDropperTrigger}>
              <Pipette />
            </ColorPicker.EyeDropperTrigger>
            <div class={styles.ChannelSliders}>
              <ColorPicker.ChannelSlider class={styles.ChannelSlider} channel="hue">
                <ColorPicker.ChannelSliderTrack class={styles.ChannelSliderTrack} />
                <ColorPicker.ChannelSliderThumb class={styles.ChannelSliderThumb} />
              </ColorPicker.ChannelSlider>
              <ColorPicker.ChannelSlider class={styles.ChannelSlider} channel="alpha">
                <ColorPicker.TransparencyGrid class={styles.TransparencyGrid} />
                <ColorPicker.ChannelSliderTrack class={styles.ChannelSliderTrack} />
                <ColorPicker.ChannelSliderThumb class={styles.ChannelSliderThumb} />
              </ColorPicker.ChannelSlider>
            </div>
          </div>
          <ColorPicker.SwatchGroup class={styles.SwatchGroup}>
            for (const color of swatches; key color) {
              <ColorPicker.SwatchTrigger class={styles.SwatchTrigger} value={color}>
                <ColorPicker.Swatch class={styles.Swatch} value={color}>
                  <ColorPicker.SwatchIndicator class={styles.SwatchIndicator}>
                    <Check />
                  </ColorPicker.SwatchIndicator>
                </ColorPicker.Swatch>
              </ColorPicker.SwatchTrigger>
            }
          </ColorPicker.SwatchGroup>
          <ColorPicker.View class={styles.View} format="rgba">
            <div class={styles.ChannelInputGroup}>
              <ColorPicker.ChannelInput class={styles.ChannelInput} channel="hex" />
              <ColorPicker.ChannelInput class={styles.ChannelInput} channel="alpha" />
            </div>
          </ColorPicker.View>
          <ColorPicker.View class={styles.View} format="hsla">
            <div class={styles.ChannelInputGroup}>
              <ColorPicker.ChannelInput class={styles.ChannelInput} channel="hue" />
              <ColorPicker.ChannelInput class={styles.ChannelInput} channel="saturation" />
              <ColorPicker.ChannelInput class={styles.ChannelInput} channel="lightness" />
            </div>
          </ColorPicker.View>
        </ColorPicker.Content>
      </ColorPicker.Positioner>
      <ColorPicker.HiddenInput />
    </ColorPicker.RootProvider>
  </div>
}

```

### Disabled

Use the `disabled` prop to disable the color picker.

**Example: disabled**

```ripple
import { ColorPicker, parseColor } from 'ark-ripple/color-picker';
import styles from 'styles/color-picker.module.css';

export component Disabled() {
  <ColorPicker.Root class={styles.Root} disabled defaultValue={parseColor('#eb5e41')}>
    <ColorPicker.Label class={styles.Label}>{'Color'}</ColorPicker.Label>
    <ColorPicker.Control class={styles.Control}>
      <ColorPicker.ChannelInput class={styles.Input} channel="hex" />
      <ColorPicker.Trigger class={styles.Trigger}>
        <div class={styles.Swatch}>
          <ColorPicker.TransparencyGrid class={styles.TransparencyGrid} />
          <ColorPicker.ValueSwatch class={styles.ValueSwatch} />
        </div>
      </ColorPicker.Trigger>
    </ColorPicker.Control>
    <ColorPicker.HiddenInput />
  </ColorPicker.Root>
}

```

### Inline

Render the color picker inline without a popover by using the `inline` prop.

**Example: inline**

```ripple
import { ColorPicker, parseColor } from 'ark-ripple/color-picker';
import { Check } from 'lucide-ripple';
import styles from 'styles/color-picker.module.css';

const swatches = ['red', 'blue', 'green', 'orange'];

export component Inline() {
  <ColorPicker.Root class={styles.Root} inline defaultValue={parseColor('#eb5e41')}>
    <ColorPicker.Area class={styles.Area}>
      <ColorPicker.AreaBackground class={styles.AreaBackground} />
      <ColorPicker.AreaThumb class={styles.AreaThumb} />
    </ColorPicker.Area>
    <ColorPicker.SwatchGroup class={styles.SwatchGroup}>
      for (const color of swatches; key color) {
        <ColorPicker.SwatchTrigger class={styles.SwatchTrigger} value={color}>
          <ColorPicker.Swatch class={styles.Swatch} value={color}>
            <ColorPicker.SwatchIndicator class={styles.SwatchIndicator}>
              <Check />
            </ColorPicker.SwatchIndicator>
          </ColorPicker.Swatch>
        </ColorPicker.SwatchTrigger>
      }
    </ColorPicker.SwatchGroup>
  </ColorPicker.Root>
}

```

### Input Only

A minimal color picker with just an input field, value swatch, and eye dropper trigger.

**Example: input-only**

```ripple
import { ColorPicker, parseColor } from 'ark-ripple/color-picker';
import { Pipette } from 'lucide-ripple';
import styles from 'styles/color-picker.module.css';

export component InputOnly() {
  <ColorPicker.Root class={styles.Root} defaultValue={parseColor('#eb5e41')}>
    <ColorPicker.Label class={styles.Label}>{'Color'}</ColorPicker.Label>
    <ColorPicker.Control class={styles.Control}>
      <ColorPicker.ValueSwatch class={styles.Swatch} />
      <ColorPicker.ChannelInput class={styles.Input} channel="hex" />
      <ColorPicker.EyeDropperTrigger class={styles.EyeDropperTrigger}>
        <Pipette />
      </ColorPicker.EyeDropperTrigger>
    </ColorPicker.Control>
    <ColorPicker.HiddenInput />
  </ColorPicker.Root>
}

```

### Slider Only

Display only the channel sliders for RGB color selection.

**Example: slider-only**

```ripple
import { ColorPicker, parseColor } from 'ark-ripple/color-picker';
import styles from 'styles/color-picker.module.css';

export component SliderOnly() {
  <ColorPicker.Root class={styles.Root} inline defaultValue={parseColor('#5dd016')}>
    <div class="hstack">
      <div class={styles.Swatch}>
        <ColorPicker.TransparencyGrid class={styles.TransparencyGrid} />
        <ColorPicker.ValueSwatch class={styles.ValueSwatch} />
      </div>
      <ColorPicker.ValueText class={styles.ValueText} />
    </div>
    <ColorPicker.View class={styles.View} format="rgba">
      <div class={styles.ChannelSliderRow}>
        <span class={styles.ChannelSliderLabel}>{'R'}</span>
        <ColorPicker.ChannelSlider class={styles.ChannelSlider} channel="red">
          <ColorPicker.TransparencyGrid class={styles.TransparencyGrid} />
          <ColorPicker.ChannelSliderTrack class={styles.ChannelSliderTrack} />
          <ColorPicker.ChannelSliderThumb class={styles.ChannelSliderThumb} />
        </ColorPicker.ChannelSlider>
      </div>
      <div class={styles.ChannelSliderRow}>
        <span class={styles.ChannelSliderLabel}>{'G'}</span>
        <ColorPicker.ChannelSlider class={styles.ChannelSlider} channel="green">
          <ColorPicker.TransparencyGrid class={styles.TransparencyGrid} />
          <ColorPicker.ChannelSliderTrack class={styles.ChannelSliderTrack} />
          <ColorPicker.ChannelSliderThumb class={styles.ChannelSliderThumb} />
        </ColorPicker.ChannelSlider>
      </div>
      <div class={styles.ChannelSliderRow}>
        <span class={styles.ChannelSliderLabel}>{'B'}</span>
        <ColorPicker.ChannelSlider class={styles.ChannelSlider} channel="blue">
          <ColorPicker.TransparencyGrid class={styles.TransparencyGrid} />
          <ColorPicker.ChannelSliderTrack class={styles.ChannelSliderTrack} />
          <ColorPicker.ChannelSliderThumb class={styles.ChannelSliderThumb} />
        </ColorPicker.ChannelSlider>
      </div>
    </ColorPicker.View>
  </ColorPicker.Root>
}

```

### Swatch Only

A simple color picker with only preset color swatches.

**Example: swatch-only**

```ripple
import { ColorPicker, parseColor } from 'ark-ripple/color-picker';
import { Check } from 'lucide-ripple';
import styles from 'styles/color-picker.module.css';

const swatches = ['red', 'pink', 'orange', 'purple'];

export component SwatchOnly() {
  <ColorPicker.Root class={styles.Root} inline defaultValue={parseColor('#eb5e41')}>
    <output>
      {'Selected color: '}
      <ColorPicker.ValueText class={styles.ValueText} />
    </output>
    <ColorPicker.SwatchGroup class={styles.SwatchGroup}>
      for (const color of swatches; key color) {
        <ColorPicker.SwatchTrigger class={styles.SwatchTrigger} value={color}>
          <ColorPicker.Swatch class={styles.Swatch} value={color}>
            <ColorPicker.SwatchIndicator class={styles.SwatchIndicator}>
              <Check />
            </ColorPicker.SwatchIndicator>
          </ColorPicker.Swatch>
        </ColorPicker.SwatchTrigger>
      }
    </ColorPicker.SwatchGroup>
  </ColorPicker.Root>
}

```

### Swatches

Include preset color swatches in the color picker content for quick color selection.

**Example: swatches**

```ripple
import { ColorPicker, parseColor } from 'ark-ripple/color-picker';
import { Check, Pipette } from 'lucide-ripple';
import styles from 'styles/color-picker.module.css';

const swatches = ['red', 'blue', 'green', 'orange'];

export component Swatches() {
  <ColorPicker.Root class={styles.Root} defaultValue={parseColor('#eb5e41')}>
    <ColorPicker.Label class={styles.Label}>{'Color'}</ColorPicker.Label>
    <ColorPicker.Control class={styles.Control}>
      <ColorPicker.ChannelInput class={styles.Input} channel="hex" />
      <ColorPicker.ChannelInput class={styles.ChannelInput} channel="alpha" />
      <ColorPicker.Trigger class={styles.Trigger}>
        <div class={styles.Swatch}>
          <ColorPicker.TransparencyGrid class={styles.TransparencyGrid} />
          <ColorPicker.ValueSwatch class={styles.ValueSwatch} />
        </div>
      </ColorPicker.Trigger>
    </ColorPicker.Control>
    <ColorPicker.Positioner>
      <ColorPicker.Content class={styles.Content}>
        <ColorPicker.Area class={styles.Area}>
          <ColorPicker.AreaBackground class={styles.AreaBackground} />
          <ColorPicker.AreaThumb class={styles.AreaThumb} />
        </ColorPicker.Area>
        <div class={styles.SliderGroup}>
          <ColorPicker.EyeDropperTrigger class={styles.EyeDropperTrigger}>
            <Pipette />
          </ColorPicker.EyeDropperTrigger>
          <div class={styles.ChannelSliders}>
            <ColorPicker.ChannelSlider class={styles.ChannelSlider} channel="hue">
              <ColorPicker.ChannelSliderTrack class={styles.ChannelSliderTrack} />
              <ColorPicker.ChannelSliderThumb class={styles.ChannelSliderThumb} />
            </ColorPicker.ChannelSlider>
            <ColorPicker.ChannelSlider class={styles.ChannelSlider} channel="alpha">
              <ColorPicker.TransparencyGrid class={styles.TransparencyGrid} />
              <ColorPicker.ChannelSliderTrack class={styles.ChannelSliderTrack} />
              <ColorPicker.ChannelSliderThumb class={styles.ChannelSliderThumb} />
            </ColorPicker.ChannelSlider>
          </div>
        </div>
        <ColorPicker.SwatchGroup class={styles.SwatchGroup}>
          for (const color of swatches; key color) {
            <ColorPicker.SwatchTrigger class={styles.SwatchTrigger} value={color}>
              <ColorPicker.Swatch class={styles.Swatch} value={color}>
                <ColorPicker.SwatchIndicator class={styles.SwatchIndicator}>
                  <Check />
                </ColorPicker.SwatchIndicator>
              </ColorPicker.Swatch>
            </ColorPicker.SwatchTrigger>
          }
        </ColorPicker.SwatchGroup>
      </ColorPicker.Content>
    </ColorPicker.Positioner>
    <ColorPicker.HiddenInput />
  </ColorPicker.Root>
}

```

### Value Swatch

Display the current color value as a swatch alongside the color area and sliders.

**Example: value-swatch**

```ripple
import { ColorPicker, parseColor } from 'ark-ripple/color-picker';
import styles from 'styles/color-picker.module.css';

export component ValueSwatch() {
  <ColorPicker.Root class={styles.Root} inline defaultValue={parseColor('#eb5e41')}>
    <ColorPicker.Area class={styles.Area}>
      <ColorPicker.AreaBackground class={styles.AreaBackground} />
      <ColorPicker.AreaThumb class={styles.AreaThumb} />
    </ColorPicker.Area>
    <div class={styles.SliderGroup}>
      <div class={styles.Swatch}>
        <ColorPicker.TransparencyGrid class={styles.TransparencyGrid} />
        <ColorPicker.ValueSwatch class={styles.ValueSwatch} />
      </div>
      <div class={styles.ChannelSliders}>
        <ColorPicker.ChannelSlider class={styles.ChannelSlider} channel="hue">
          <ColorPicker.ChannelSliderTrack class={styles.ChannelSliderTrack} />
          <ColorPicker.ChannelSliderThumb class={styles.ChannelSliderThumb} />
        </ColorPicker.ChannelSlider>
        <ColorPicker.ChannelSlider class={styles.ChannelSlider} channel="alpha">
          <ColorPicker.TransparencyGrid class={styles.TransparencyGrid} />
          <ColorPicker.ChannelSliderTrack class={styles.ChannelSliderTrack} />
          <ColorPicker.ChannelSliderThumb class={styles.ChannelSliderThumb} />
        </ColorPicker.ChannelSlider>
      </div>
    </div>
  </ColorPicker.Root>
}

```

### Field

The `Field` component helps manage form-related state and accessibility attributes of a color picker. It includes
handling ARIA labels, helper text, and error text to ensure proper accessibility.

**Example: with-field**

```ripple
import { ColorPicker, parseColor } from 'ark-ripple/color-picker';
import { Field } from 'ark-ripple/field';
import styles from 'styles/color-picker.module.css';
import field from 'styles/field.module.css';

export component WithField() {
  <Field.Root class={field.Root}>
    <ColorPicker.Root class={styles.Root} defaultValue={parseColor('#eb5e41')}>
      <ColorPicker.Label class={styles.Label}>{'Label'}</ColorPicker.Label>
      <ColorPicker.Control class={styles.Control}>
        <ColorPicker.ChannelInput class={styles.Input} channel="hex" />
        <ColorPicker.ChannelInput class={styles.ChannelInput} channel="alpha" />
        <ColorPicker.Trigger class={styles.Trigger}>
          <div class={styles.Swatch}>
            <ColorPicker.TransparencyGrid class={styles.TransparencyGrid} />
            <ColorPicker.ValueSwatch class={styles.ValueSwatch} />
          </div>
        </ColorPicker.Trigger>
      </ColorPicker.Control>
      <ColorPicker.Positioner>
        <ColorPicker.Content class={styles.Content} />
      </ColorPicker.Positioner>
      <ColorPicker.HiddenInput />
    </ColorPicker.Root>
    <Field.HelperText class={field.HelperText}>{'Additional Info'}</Field.HelperText>
    <Field.ErrorText class={field.ErrorText}>{'Error Info'}</Field.ErrorText>
  </Field.Root>
}

```

### Form Usage

Integrate the color picker with form libraries like React Hook Form using the `HiddenInput` component.

**Example: form-usage**

```ripple
import { ColorPicker, parseColor } from 'ark-ripple/color-picker';
import { Pipette } from 'lucide-ripple';
import styles from 'styles/color-picker.module.css';
import button from 'styles/button.module.css';

export component FormUsage() {
  const onSubmit = (e: Event) => {
    e.preventDefault();
    const form = e.target as HTMLFormElement;
    alert(JSON.stringify(Object.fromEntries(new FormData(form))));
  };

  <form {onSubmit}>
    <ColorPicker.Root class={styles.Root} inline defaultValue={parseColor('#eb5e41')}>
      <ColorPicker.HiddenInput name="color" />
      <ColorPicker.Area class={styles.Area}>
        <ColorPicker.AreaBackground class={styles.AreaBackground} />
        <ColorPicker.AreaThumb class={styles.AreaThumb} />
      </ColorPicker.Area>
      <div class={styles.SliderGroup}>
        <ColorPicker.EyeDropperTrigger class={styles.EyeDropperTrigger}>
          <Pipette />
        </ColorPicker.EyeDropperTrigger>
        <div class={styles.ChannelSliders}>
          <ColorPicker.ChannelSlider class={styles.ChannelSlider} channel="hue">
            <ColorPicker.ChannelSliderTrack class={styles.ChannelSliderTrack} />
            <ColorPicker.ChannelSliderThumb class={styles.ChannelSliderThumb} />
          </ColorPicker.ChannelSlider>
          <ColorPicker.ChannelSlider class={styles.ChannelSlider} channel="alpha">
            <ColorPicker.TransparencyGrid class={styles.TransparencyGrid} />
            <ColorPicker.ChannelSliderTrack class={styles.ChannelSliderTrack} />
            <ColorPicker.ChannelSliderThumb class={styles.ChannelSliderThumb} />
          </ColorPicker.ChannelSlider>
        </div>
      </div>
      <ColorPicker.View class={styles.View} format="rgba">
        <div class={styles.ChannelInputGroup}>
          <ColorPicker.ChannelInput class={styles.ChannelInput} channel="hex" />
          <ColorPicker.ChannelInput class={styles.ChannelInput} channel="alpha" />
        </div>
      </ColorPicker.View>
      <ColorPicker.View class={styles.View} format="hsla">
        <div class={styles.ChannelInputGroup}>
          <ColorPicker.ChannelInput class={styles.ChannelInput} channel="hue" />
          <ColorPicker.ChannelInput class={styles.ChannelInput} channel="saturation" />
          <ColorPicker.ChannelInput class={styles.ChannelInput} channel="lightness" />
        </div>
      </ColorPicker.View>
      <button class={button.Root} type="submit" data-variant="solid">{'Submit'}</button>
    </ColorPicker.Root>
  </form>
}

```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `closeOnSelect` | `boolean` | No | Whether to close the color picker when a swatch is selected |
| `defaultFormat` | `ColorFormat` | No | The initial color format when rendered.
Use when you don't need to control the color format of the color picker. |
| `defaultOpen` | `boolean` | No | The initial open state of the color picker when rendered.
Use when you don't need to control the open state of the color picker. |
| `defaultValue` | `Color` | No | The initial color value when rendered.
Use when you don't need to control the color value of the color picker. |
| `disabled` | `boolean` | No | Whether the color picker is disabled |
| `format` | `ColorFormat` | No | The controlled color format to use |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{ root: string; control: string; trigger: string; label: string; input: string; hiddenInput: string; content: string; area: string; areaGradient: string; positioner: string; formatSelect: string; areaThumb: string; channelInput: (id: string) => string; channelSliderTrack: (id: ColorChannel) => string; channe...` | No | The ids of the elements in the color picker. Useful for composition. |
| `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame |
| `initialFocusEl` | `() => HTMLElement | null` | No | The initial focus element when the color picker is opened. |
| `inline` | `boolean` | No | Whether to render the color picker inline |
| `invalid` | `boolean` | No | Whether the color picker is invalid |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `name` | `string` | No | The name for the form input |
| `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state |
| `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component |
| `onFormatChange` | `(details: FormatChangeDetails) => void` | No | Function called when the color format changes |
| `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component |
| `onOpenChange` | `(details: OpenChangeDetails) => void` | No | Handler that is called when the user opens or closes the color picker. |
| `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | Handler that is called when the value changes, as the user drags. |
| `onValueChangeEnd` | `(details: ValueChangeDetails) => void` | No | Handler that is called when the user stops dragging. |
| `open` | `boolean` | No | The controlled open state of the color picker |
| `openAutoFocus` | `boolean` | No | Whether to auto focus the color picker when it is opened |
| `positioning` | `PositioningOptions` | No | The positioning options for the color picker |
| `present` | `boolean` | No | Whether the node is present (controlled by the user) |
| `readOnly` | `boolean` | No | Whether the color picker is read-only |
| `required` | `boolean` | No | Whether the color picker is required |
| `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |
| `value` | `Color` | No | The controlled color value of the color picker |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | color-picker |
| `[data-part]` | root |
| `[data-disabled]` | Present when disabled |
| `[data-readonly]` | Present when read-only |
| `[data-invalid]` | Present when invalid |


**Root CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--value` | The current value |


**AreaBackground Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**AreaBackground Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | color-picker |
| `[data-part]` | area-background |
| `[data-invalid]` | Present when invalid |
| `[data-disabled]` | Present when disabled |
| `[data-readonly]` | Present when read-only |


**Area Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `xChannel` | `ColorChannel` | No |  |
| `yChannel` | `ColorChannel` | No |  |


**Area Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | color-picker |
| `[data-part]` | area |
| `[data-invalid]` | Present when invalid |
| `[data-disabled]` | Present when disabled |
| `[data-readonly]` | Present when read-only |


**AreaThumb Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**AreaThumb Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | color-picker |
| `[data-part]` | area-thumb |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]` | Present when invalid |
| `[data-readonly]` | Present when read-only |


**AreaThumb CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--color` | The text color |


**ChannelInput Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `channel` | `ExtendedColorChannel` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `orientation` | `Orientation` | No |  |


**ChannelInput Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | color-picker |
| `[data-part]` | channel-input |
| `[data-channel]` | The color channel of the channelinput |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]` | Present when invalid |
| `[data-readonly]` | Present when read-only |


**ChannelSliderLabel Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ChannelSliderLabel Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | color-picker |
| `[data-part]` | channel-slider-label |
| `[data-channel]` | The color channel of the channelsliderlabel |


**ChannelSlider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `channel` | `ColorChannel` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `orientation` | `Orientation` | No |  |


**ChannelSlider Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | color-picker |
| `[data-part]` | channel-slider |
| `[data-channel]` | The color channel of the channelslider |
| `[data-orientation]` | The orientation of the channelslider |


**ChannelSliderThumb Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ChannelSliderThumb Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | color-picker |
| `[data-part]` | channel-slider-thumb |
| `[data-channel]` | The color channel of the channelsliderthumb |
| `[data-disabled]` | Present when disabled |
| `[data-orientation]` | The orientation of the channelsliderthumb |


**ChannelSliderTrack Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ChannelSliderTrack Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | color-picker |
| `[data-part]` | channel-slider-track |
| `[data-channel]` | The color channel of the channelslidertrack |
| `[data-orientation]` | The orientation of the channelslidertrack |


**ChannelSliderValueText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ChannelSliderValueText Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | color-picker |
| `[data-part]` | channel-slider-value-text |
| `[data-channel]` | The color channel of the channelslidervaluetext |


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | color-picker |
| `[data-part]` | content |
| `[data-placement]` | The placement of the content |
| `[data-nested]` | popover |
| `[data-has-nested]` | popover |
| `[data-state]` | "open" | "closed" |


**Content CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--layer-index` | The index of the dismissable in the layer stack |
| `--nested-layer-count` | The number of nested color-pickers |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | color-picker |
| `[data-part]` | control |
| `[data-disabled]` | Present when disabled |
| `[data-readonly]` | Present when read-only |
| `[data-invalid]` | Present when invalid |
| `[data-state]` | "open" | "closed" |
| `[data-focus]` | Present when focused |


**EyeDropperTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**EyeDropperTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | color-picker |
| `[data-part]` | eye-dropper-trigger |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]` | Present when invalid |
| `[data-readonly]` | Present when read-only |


**FormatSelect Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**FormatTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**HiddenInput Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | color-picker |
| `[data-part]` | label |
| `[data-disabled]` | Present when disabled |
| `[data-readonly]` | Present when read-only |
| `[data-invalid]` | Present when invalid |
| `[data-required]` | Present when required |
| `[data-focus]` | Present when focused |


**Positioner Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Positioner CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--reference-width` | The width of the reference element |
| `--reference-height` | The height of the root |
| `--available-width` | The available width in viewport |
| `--available-height` | The available height in viewport |
| `--x` | The x position for transform |
| `--y` | The y position for transform |
| `--z-index` | The z-index value |
| `--transform-origin` | The transform origin for animations |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseColorPickerReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state |
| `present` | `boolean` | No | Whether the node is present (controlled by the user) |
| `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


**SwatchGroup Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**SwatchIndicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Swatch Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `string | Color` | Yes | The color value |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `respectAlpha` | `boolean` | No | Whether to include the alpha channel in the color |


**Swatch Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | color-picker |
| `[data-part]` | swatch |
| `[data-state]` | "checked" | "unchecked" |
| `[data-value]` | The value of the item |


**Swatch CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--color` | The text color |


**SwatchTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `string | Color` | Yes | The color value |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `disabled` | `boolean` | No | Whether the swatch trigger is disabled |


**SwatchTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | color-picker |
| `[data-part]` | swatch-trigger |
| `[data-state]` | "checked" | "unchecked" |
| `[data-value]` | The value of the item |
| `[data-disabled]` | Present when disabled |


**SwatchTrigger CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--color` | The text color |


**TransparencyGrid Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `size` | `string` | No |  |


**TransparencyGrid CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--size` | The size (width and height) of the element |


**Trigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | color-picker |
| `[data-part]` | trigger |
| `[data-disabled]` | Present when disabled |
| `[data-readonly]` | Present when read-only |
| `[data-invalid]` | Present when invalid |
| `[data-placement]` | The placement of the trigger |
| `[data-state]` | "open" | "closed" |
| `[data-focus]` | Present when focused |


**ValueSwatch Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `respectAlpha` | `boolean` | No | Whether to include the alpha channel in the color |


**ValueText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `format` | `ColorStringFormat` | No |  |


**ValueText Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | color-picker |
| `[data-part]` | value-text |
| `[data-disabled]` | Present when disabled |
| `[data-focus]` | Present when focused |


**View Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `format` | `ColorFormat` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `dragging` | `boolean` | Whether the color picker is being dragged |
| `open` | `boolean` | Whether the color picker is open |
| `inline` | `boolean` | Whether the color picker is rendered inline |
| `value` | `Color` | The current color value (as a string) |
| `valueAsString` | `string` | The current color value (as a Color object) |
| `setValue` | `(value: string | Color) => void` | Function to set the color value |
| `getChannelValue` | `(channel: ColorChannel) => string` | Function to set the color value |
| `getChannelValueText` | `(channel: ColorChannel, locale: string) => string` | Function to get the formatted and localized value of a specific channel |
| `setChannelValue` | `(channel: ColorChannel, value: number) => void` | Function to set the color value of a specific channel |
| `format` | `ColorFormat` | The current color format |
| `setFormat` | `(format: ColorFormat) => void` | Function to set the color format |
| `alpha` | `number` | The alpha value of the color |
| `setAlpha` | `(value: number) => void` | Function to set the color alpha |
| `setOpen` | `(open: boolean) => void` | Function to open or close the color picker |


## Accessibility

### Keyboard Support

**`Enter`**
Description: <span>When focus is on the trigger, opens the color picker<br />When focus is on a trigger of a swatch, selects the color (and closes the color picker)<br />When focus is on the input or channel inputs, selects the color</span>

**`ArrowLeft`**
Description: <span>When focus is on the color area, decreases the hue value of the color<br />When focus is on the channel sliders, decreases the value of the channel</span>

**`ArrowRight`**
Description: <span>When focus is on the color area, increases the hue value of the color<br />When focus is on the channel sliders, increases the value of the channel</span>

**`ArrowUp`**
Description: <span>When focus is on the color area, increases the saturation value of the color<br />When focus is on the channel sliders, increases the value of the channel</span>

**`ArrowDown`**
Description: <span>When focus is on the color area, decreases the saturation value of the color<br />When focus is on the channel sliders, decreases the value of the channel</span>

**`Esc`**
Description: Closes the color picker and moves focus to the trigger


# Combobox 



## Anatomy



```tsx
<Combobox.Root>
  <Combobox.Label />
  <Combobox.Control>
    <Combobox.Input />
    <Combobox.Trigger />
    <Combobox.ClearTrigger />
  </Combobox.Control>
  <Combobox.Positioner>
    <Combobox.Content>
      <Combobox.ItemGroup>
        <Combobox.ItemGroupLabel />
        <Combobox.Item>
          <Combobox.ItemText />
          <Combobox.ItemIndicator />
        </Combobox.Item>
      </Combobox.ItemGroup>
    </Combobox.Content>
  </Combobox.Positioner>
</Combobox.Root>
```

## Examples

**Example: basic**

```ripple
import { Combobox, useListCollection } from 'ark-ripple/combobox';
import { useFilter } from 'ark-ripple/locale';
import { Portal } from 'ark-ripple/portal';
import { Check, ChevronsUpDown, X } from 'lucide-ripple';
import styles from 'styles/combobox.module.css';

export component Basic() {
  const filterApi = useFilter({ sensitivity: 'base' });

  let { collection, filter } = useListCollection(
    {
      initialItems: [
        { label: 'Apple', value: 'apple' },
        { label: 'Banana', value: 'banana' },
        { label: 'Orange', value: 'orange' },
        { label: 'Mango', value: 'mango' },
        { label: 'Pineapple', value: 'pineapple' },
        { label: 'Strawberry', value: 'strawberry' },
      ],
      filter: @filterApi.contains,
    },
  );

  <Combobox.Root
    class={styles.Root}
    {collection}
    onInputValueChange={(details) => {
      filter(details.inputValue);
    }}
  >
    <Combobox.Label class={styles.Label}>{'Favorite Fruit'}</Combobox.Label>
    <Combobox.Control class={styles.Control}>
      <Combobox.Input class={styles.Input} placeholder="e.g. Apple" />
      <div class={styles.Indicators}>
        <Combobox.ClearTrigger class={styles.ClearTrigger}>
          <X />
        </Combobox.ClearTrigger>
        <Combobox.Trigger class={styles.Trigger}>
          <ChevronsUpDown />
        </Combobox.Trigger>
      </div>
    </Combobox.Control>
    <Portal>
      <Combobox.Positioner>
        <Combobox.Content class={styles.Content}>
          for (const item of @collection.items; key item.value) {
            <Combobox.Item class={styles.Item} {item}>
              <Combobox.ItemText class={styles.ItemText}>{item.label}</Combobox.ItemText>
              <Combobox.ItemIndicator class={styles.ItemIndicator}>
                <Check />
              </Combobox.ItemIndicator>
            </Combobox.Item>
          }
        </Combobox.Content>
      </Combobox.Positioner>
    </Portal>
  </Combobox.Root>
}

```

### Auto Highlight

Automatically highlight the first matching item as the user types by setting `inputBehavior="autohighlight"`.

**Example: auto-highlight**

```ripple
import { Combobox, useListCollection } from 'ark-ripple/combobox';
import { useFilter } from 'ark-ripple/locale';
import { Portal } from 'ark-ripple/portal';
import { Check, ChevronsUpDown, X } from 'lucide-ripple';
import styles from 'styles/combobox.module.css';

export component AutoHighlight() {
  const filterApi = useFilter({ sensitivity: 'base' });

  let { collection, filter } = useListCollection(
    {
      initialItems: [
        { label: 'Engineering', value: 'engineering' },
        { label: 'Marketing', value: 'marketing' },
        { label: 'Sales', value: 'sales' },
        { label: 'Finance', value: 'finance' },
        { label: 'Human Resources', value: 'hr' },
        { label: 'Operations', value: 'operations' },
        { label: 'Product', value: 'product' },
        { label: 'Customer Success', value: 'customer-success' },
        { label: 'Legal', value: 'legal' },
        { label: 'Information Technology', value: 'information-technology' },
        { label: 'Design', value: 'design' },
      ],
      filter: @filterApi.contains,
    },
  );

  const handleInputChange = (details: Combobox.InputValueChangeDetails) => {
    filter(details.inputValue);
  };

  <Combobox.Root
    class={styles.Root}
    {collection}
    onInputValueChange={handleInputChange}
    inputBehavior="autohighlight"
  >
    <Combobox.Label class={styles.Label}>{'Department'}</Combobox.Label>
    <Combobox.Control class={styles.Control}>
      <Combobox.Input class={styles.Input} placeholder="e.g. Engineering" />
      <div class={styles.Indicators}>
        <Combobox.ClearTrigger class={styles.ClearTrigger}>
          <X />
        </Combobox.ClearTrigger>
        <Combobox.Trigger class={styles.Trigger}>
          <ChevronsUpDown />
        </Combobox.Trigger>
      </div>
    </Combobox.Control>
    <Portal>
      <Combobox.Positioner>
        <Combobox.Content class={styles.Content}>
          <Combobox.Empty class={styles.Item}>{'No results found'}</Combobox.Empty>
          for (const item of @collection.items; key item.value) {
            <Combobox.Item class={styles.Item} {item}>
              <Combobox.ItemText class={styles.ItemText}>{item.label}</Combobox.ItemText>
              <Combobox.ItemIndicator class={styles.ItemIndicator}>
                <Check />
              </Combobox.ItemIndicator>
            </Combobox.Item>
          }
        </Combobox.Content>
      </Combobox.Positioner>
    </Portal>
  </Combobox.Root>
}

```

### Inline Autocomplete

Complete the input value with the first matching item by setting `inputBehavior="autocomplete"`. Use with `startsWith`
filter for best results.

**Example: inline-autocomplete**

```ripple
import { Combobox, useListCollection } from 'ark-ripple/combobox';
import { useFilter } from 'ark-ripple/locale';
import { Portal } from 'ark-ripple/portal';
import { Check, ChevronsUpDown, X } from 'lucide-ripple';
import styles from 'styles/combobox.module.css';

export component InlineAutocomplete() {
  const filterApi = useFilter({ sensitivity: 'base' });

  let { collection, filter } = useListCollection(
    {
      initialItems: [
        { label: 'Whale', value: 'whale' },
        { label: 'Dolphin', value: 'dolphin' },
        { label: 'Shark', value: 'shark' },
        { label: 'Octopus', value: 'octopus' },
        { label: 'Jellyfish', value: 'jellyfish' },
        { label: 'Seahorse', value: 'seahorse' },
      ],
      filter: @filterApi.startsWith,
    },
  );

  const handleInputChange = (details: Combobox.InputValueChangeDetails) => {
    filter(details.inputValue);
  };

  <Combobox.Root
    class={styles.Root}
    {collection}
    onInputValueChange={handleInputChange}
    inputBehavior="autocomplete"
  >
    <Combobox.Label class={styles.Label}>{'Sea Creature'}</Combobox.Label>
    <Combobox.Control class={styles.Control}>
      <Combobox.Input class={styles.Input} placeholder="e.g. Dolphin" />
      <div class={styles.Indicators}>
        <Combobox.ClearTrigger class={styles.ClearTrigger}>
          <X />
        </Combobox.ClearTrigger>
        <Combobox.Trigger class={styles.Trigger}>
          <ChevronsUpDown />
        </Combobox.Trigger>
      </div>
    </Combobox.Control>
    <Portal>
      <Combobox.Positioner>
        <Combobox.Content class={styles.Content}>
          <Combobox.Empty class={styles.Item}>{'No results found'}</Combobox.Empty>
          for (const item of @collection.items; key item.value) {
            <Combobox.Item class={styles.Item} {item}>
              <Combobox.ItemText class={styles.ItemText}>{item.label}</Combobox.ItemText>
              <Combobox.ItemIndicator class={styles.ItemIndicator}>
                <Check />
              </Combobox.ItemIndicator>
            </Combobox.Item>
          }
        </Combobox.Content>
      </Combobox.Positioner>
    </Portal>
  </Combobox.Root>
}

```

### Grouping

To group related combobox items, use the `groupBy` prop on the collection and `collection.group()` to iterate the
groups.

**Example: grouping**

```ripple
import { Combobox, useListCollection } from 'ark-ripple/combobox';
import { useFilter } from 'ark-ripple/locale';
import { Portal } from 'ark-ripple/portal';
import { Check, ChevronsUpDown, X } from 'lucide-ripple';
import styles from 'styles/combobox.module.css';

export component Grouping() {
  const filterApi = useFilter({ sensitivity: 'base' });

  let { collection, filter } = useListCollection(
    {
      initialItems,
      filter: @filterApi.contains,
      groupBy: (item) => item.continent,
    },
  );

  const handleInputChange = (details: Combobox.InputValueChangeDetails) => {
    filter(details.inputValue);
  };

  <Combobox.Root class={styles.Root} {collection} onInputValueChange={handleInputChange}>
    <Combobox.Label class={styles.Label}>{'Country'}</Combobox.Label>
    <Combobox.Control class={styles.Control}>
      <Combobox.Input class={styles.Input} placeholder="e.g. Canada" />
      <div class={styles.Indicators}>
        <Combobox.ClearTrigger class={styles.ClearTrigger}>
          <X />
        </Combobox.ClearTrigger>
        <Combobox.Trigger class={styles.Trigger}>
          <ChevronsUpDown />
        </Combobox.Trigger>
      </div>
    </Combobox.Control>
    <Portal>
      <Combobox.Positioner>
        <Combobox.Content class={styles.Content}>
          for (const [continent, group] of @collection.group(); key continent) {
            <Combobox.ItemGroup class={styles.ItemGroup}>
              <Combobox.ItemGroupLabel class={styles.ItemGroupLabel}>
                {continent}
              </Combobox.ItemGroupLabel>
              for (const item of group; key item.value) {
                <Combobox.Item class={styles.Item} {item}>
                  <Combobox.ItemText class={styles.ItemText}>{item.label}</Combobox.ItemText>
                  <Combobox.ItemIndicator class={styles.ItemIndicator}>
                    <Check />
                  </Combobox.ItemIndicator>
                </Combobox.Item>
              }
            </Combobox.ItemGroup>
          }
        </Combobox.Content>
      </Combobox.Positioner>
    </Portal>
  </Combobox.Root>
}

const initialItems = [
  { label: 'Canada', value: 'ca', continent: 'North America' },
  { label: 'United States', value: 'us', continent: 'North America' },
  { label: 'Mexico', value: 'mx', continent: 'North America' },
  { label: 'United Kingdom', value: 'uk', continent: 'Europe' },
  { label: 'Germany', value: 'de', continent: 'Europe' },
  { label: 'France', value: 'fr', continent: 'Europe' },
  { label: 'Japan', value: 'jp', continent: 'Asia' },
  { label: 'South Korea', value: 'kr', continent: 'Asia' },
  { label: 'China', value: 'cn', continent: 'Asia' },
];

```

### Field

The `Field` component helps manage form-related state and accessibility attributes of a combobox. It includes handling
ARIA labels, helper text, and error text to ensure proper accessibility.

**Example: with-field**

```ripple
import { Combobox, useListCollection } from 'ark-ripple/combobox';
import { Field } from 'ark-ripple/field';
import { useFilter } from 'ark-ripple/locale';
import { Check, ChevronsUpDown, X } from 'lucide-ripple';
import field from 'styles/field.module.css';
import styles from 'styles/combobox.module.css';

const initialItems = [
  { label: 'Engineering', value: 'engineering' },
  { label: 'Design', value: 'design' },
  { label: 'Marketing', value: 'marketing' },
  { label: 'Sales', value: 'sales' },
  { label: 'Human Resources', value: 'hr' },
  { label: 'Finance', value: 'finance' },
];

export component WithField() {
  const filterApi = useFilter({ sensitivity: 'base' });

  let { collection, filter } = useListCollection(
    {
      initialItems,
      filter: @filterApi.contains,
    },
  );

  const handleInputChange = (details: Combobox.InputValueChangeDetails) => {
    filter(details.inputValue);
  };

  <Field.Root class={field.Root}>
    <Combobox.Root class={styles.Root} {collection} onInputValueChange={handleInputChange}>
      <Combobox.Label class={styles.Label}>{'Department'}</Combobox.Label>
      <Combobox.Control class={styles.Control}>
        <Combobox.Input class={styles.Input} placeholder="e.g. Engineering" />
        <div class={styles.Indicators}>
          <Combobox.ClearTrigger class={styles.ClearTrigger}>
            <X />
          </Combobox.ClearTrigger>
          <Combobox.Trigger class={styles.Trigger}>
            <ChevronsUpDown />
          </Combobox.Trigger>
        </div>
      </Combobox.Control>
      <Combobox.Positioner>
        <Combobox.Content class={styles.Content}>
          for (const item of @collection.items; key item.value) {
            <Combobox.Item class={styles.Item} {item}>
              <Combobox.ItemText class={styles.ItemText}>{item.label}</Combobox.ItemText>
              <Combobox.ItemIndicator class={styles.ItemIndicator}>
                <Check />
              </Combobox.ItemIndicator>
            </Combobox.Item>
          }
        </Combobox.Content>
      </Combobox.Positioner>
    </Combobox.Root>
    <Field.HelperText class={field.HelperText}>{'Select your primary department'}</Field.HelperText>
    <Field.ErrorText class={field.ErrorText}>{'Department is required'}</Field.ErrorText>
  </Field.Root>
}

```

### Context

Access the combobox's state with `Combobox.Context` or the `useComboboxContext` hook—useful for displaying the selected
value or building custom UI.

**Example: context**

```ripple
import { Combobox, useListCollection } from 'ark-ripple/combobox';
import { useFilter } from 'ark-ripple/locale';
import { Portal } from 'ark-ripple/portal';
import { Check, ChevronsUpDown, X } from 'lucide-ripple';
import styles from 'styles/combobox.module.css';

export component Context() {
  const filterApi = useFilter({ sensitivity: 'base' });

  let { collection, filter } = useListCollection(
    {
      initialItems: [
        { label: 'Small', value: 'sm' },
        { label: 'Medium', value: 'md' },
        { label: 'Large', value: 'lg' },
        { label: 'Extra Large', value: 'xl' },
      ],
      filter: @filterApi.contains,
    },
  );

  const handleInputChange = (details: Combobox.InputValueChangeDetails) => {
    filter(details.inputValue);
  };

  <Combobox.Root class={styles.Root} {collection} onInputValueChange={handleInputChange}>
    <Combobox.Context>
      component children({ context }) {
        <p>
          {'Selected: '}
          {@context.valueAsString || 'None'}
        </p>
      }
    </Combobox.Context>
    <Combobox.Label class={styles.Label}>{'Size'}</Combobox.Label>
    <Combobox.Control class={styles.Control}>
      <Combobox.Input class={styles.Input} placeholder="e.g. Medium" />
      <div class={styles.Indicators}>
        <Combobox.ClearTrigger class={styles.ClearTrigger}>
          <X />
        </Combobox.ClearTrigger>
        <Combobox.Trigger class={styles.Trigger}>
          <ChevronsUpDown />
        </Combobox.Trigger>
      </div>
    </Combobox.Control>
    <Portal>
      <Combobox.Positioner>
        <Combobox.Content class={styles.Content}>
          for (const item of @collection.items; key item.value) {
            <Combobox.Item class={styles.Item} {item}>
              <Combobox.ItemText class={styles.ItemText}>{item.label}</Combobox.ItemText>
              <Combobox.ItemIndicator class={styles.ItemIndicator}>
                <Check />
              </Combobox.ItemIndicator>
            </Combobox.Item>
          }
        </Combobox.Content>
      </Combobox.Positioner>
    </Portal>
  </Combobox.Root>
}

```

### Root Provider

An alternative way to control the combobox is to use the `RootProvider` component and the `useCombobox` hook. This way
you can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { Combobox, useCombobox, useListCollection } from 'ark-ripple/combobox';
import { useFilter } from 'ark-ripple/locale';
import { Portal } from 'ark-ripple/portal';
import { Check, ChevronsUpDown, X } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/combobox.module.css';

const initialItems = [
  { label: 'Designer', value: 'designer' },
  { label: 'Developer', value: 'developer' },
  { label: 'Product Manager', value: 'pm' },
  { label: 'Data Scientist', value: 'data-scientist' },
  { label: 'DevOps Engineer', value: 'devops' },
  { label: 'Marketing Lead', value: 'marketing' },
];

export component RootProvider() {
  const filterApi = useFilter({ sensitivity: 'base' });

  let { collection, filter } = useListCollection(
    {
      initialItems,
      filter: @filterApi.contains,
    },
  );

  const combobox = useCombobox(
    {
      collection,
      onInputValueChange: (details) => {
        filter(details.inputValue);
      },
    },
  );

  <div>
    <button
      class={button.Root}
      type="button"
      onClick={() => {
        @combobox.focus();
      }}
    >
      {'Focus'}
    </button>

    <Combobox.RootProvider class={styles.Root} value={combobox}>
      <Combobox.Label class={styles.Label}>{'Job Title'}</Combobox.Label>
      <Combobox.Control class={styles.Control}>
        <Combobox.Input class={styles.Input} placeholder="e.g. Designer" />
        <div class={styles.Indicators}>
          <Combobox.ClearTrigger class={styles.ClearTrigger}>
            <X />
          </Combobox.ClearTrigger>
          <Combobox.Trigger class={styles.Trigger}>
            <ChevronsUpDown />
          </Combobox.Trigger>
        </div>
      </Combobox.Control>
      <Portal>
        <Combobox.Positioner>
          <Combobox.Content class={styles.Content}>
            for (const item of @collection.items; key item.value) {
              <Combobox.Item class={styles.Item} {item}>
                <Combobox.ItemText class={styles.ItemText}>{item.label}</Combobox.ItemText>
                <Combobox.ItemIndicator class={styles.ItemIndicator}>
                  <Check />
                </Combobox.ItemIndicator>
              </Combobox.Item>
            }
          </Combobox.Content>
        </Combobox.Positioner>
      </Portal>
    </Combobox.RootProvider>
  </div>
}

```

### Links

Use the `asChild` prop to render the combobox items as links.

**Example: links**

```ripple
import { Combobox, useListCollection } from 'ark-ripple/combobox';
import { useFilter } from 'ark-ripple/locale';
import { Portal } from 'ark-ripple/portal';
import { Check, ChevronsUpDown } from 'lucide-ripple';
import styles from 'styles/combobox.module.css';

export component Links() {
  const filterApi = useFilter({ sensitivity: 'base' });

  let { collection, filter } = useListCollection(
    {
      initialItems,
      filter: @filterApi.contains,
    },
  );

  const handleInputChange = (details: Combobox.InputValueChangeDetails) => {
    filter(details.inputValue);
  };

  <Combobox.Root
    class={styles.Root}
    {collection}
    onInputValueChange={handleInputChange}
    selectionBehavior="preserve"
  >
    <Combobox.Label class={styles.Label}>{'Developer Resources'}</Combobox.Label>
    <Combobox.Control class={styles.Control}>
      <Combobox.Input class={styles.Input} placeholder="e.g. GitHub" />
      <div class={styles.Indicators}>
        <Combobox.Trigger class={styles.Trigger}>
          <ChevronsUpDown />
        </Combobox.Trigger>
      </div>
    </Combobox.Control>
    <Portal>
      <Combobox.Positioner>
        <Combobox.Content class={styles.Content}>
          for (const item of @collection.items; key item.value) {
            <Combobox.Item class={styles.Item} {item}>
              component asChild({ propsFn }) {
                <a {...propsFn({ href: item.href })}>
                  <Combobox.ItemText class={styles.ItemText}>{item.label}</Combobox.ItemText>
                  <Combobox.ItemIndicator class={styles.ItemIndicator}>
                    <Check />
                  </Combobox.ItemIndicator>
                </a>
              }
            </Combobox.Item>
          }
        </Combobox.Content>
      </Combobox.Positioner>
    </Portal>
  </Combobox.Root>
}

const initialItems = [
  { label: 'GitHub', href: 'https://github.com', value: 'github' },
  { label: 'Stack Overflow', href: 'https://stackoverflow.com', value: 'stackoverflow' },
  { label: 'MDN Web Docs', href: 'https://developer.mozilla.org', value: 'mdn' },
  { label: 'npm', href: 'https://www.npmjs.com', value: 'npm' },
  { label: 'TypeScript', href: 'https://www.typescriptlang.org', value: 'typescript' },
  { label: 'React', href: 'https://react.dev', value: 'react' },
];

```

### Rehydrate

When a combobox has a `defaultValue` or `value` but the `collection` is not loaded yet, you can rehydrate the value to
populate the input.

**Example: rehydrate-value**

```ripple
import { Combobox, useCombobox, useComboboxContext, useListCollection } from 'ark-ripple/combobox';
import { Portal } from 'ark-ripple/portal';
import { Check } from 'lucide-ripple';
import { track, effect } from 'ripple';
import styles from 'styles/combobox.module.css';
import { useAsync } from './use-async';

export component RehydrateValue() {
  let inputValue = track('');

  let { collection, set } = useListCollection<Character>(
    {
      initialItems: [],
      itemToString: (item) => item.name,
      itemToValue: (item) => item.name,
    },
  );

  const combobox = useCombobox(
    {
      collection,
      defaultValue: ['C-3PO'],
      placeholder: 'Example: Dexter',
      inputValue,
      onInputValueChange: (e) => {
        @inputValue = e.inputValue;
      },
    },
  );

  let state = useAsync(async (signal) => {
    const response = await fetch(`https://swapi.py4e.com/api/people/?search=${@inputValue}`, {
      signal,
    });
    const data = await response.json();
    set(data.results);
  });

  effect(() => {
    void @inputValue;
    void state.load();
  });

  let hydrated = false;
  effect(() => {
    if (@combobox.value.length && @combobox.collection.size && !hydrated) {
      @combobox.syncSelectedItems();
      hydrated = true;
    }
  });

  <Combobox.RootProvider class={styles.Root} value={combobox}>
    <Combobox.Label class={styles.Label}>{'Search Star Wars Characters'}</Combobox.Label>
    <Combobox.Control class={styles.Control}>
      <Combobox.Input class={styles.Input} placeholder="e.g. Luke" />
    </Combobox.Control>
    <Portal>
      <Combobox.Positioner>
        <Combobox.Content class={styles.Content}>
          if (state.@loading) {
            <span style={{ padding: '0.5rem' }}>{'Loading...'}</span>
          } else if (state.@error) {
            <span style={{ padding: '0.5rem' }}>{state.@error?.message}</span>
          } else {
            for (const item of @collection.items; key item.name) {
              <Combobox.Item class={styles.Item} {item}>
                <Combobox.ItemText class={styles.ItemText}>
                  {item.name}
                  {' - '}
                  {item.height}
                  {'cm / '}
                  {item.mass}
                  {'kg'}
                </Combobox.ItemText>
                <Combobox.ItemIndicator class={styles.ItemIndicator}>
                  <Check />
                </Combobox.ItemIndicator>
              </Combobox.Item>
            }
          }
        </Combobox.Content>
      </Combobox.Positioner>
    </Portal>
  </Combobox.RootProvider>
}

interface Character {
  name: string;
  height: string;
  mass: string;
  created: string;
  edited: string;
  url: string;
}

```

### Highlight Text

Highlight the matching search text in combobox items based on the user's input.

**Example: highlight-matching-text**

```ripple
import { Combobox, useListCollection } from 'ark-ripple/combobox';
import { Highlight } from 'ark-ripple/highlight';
import { useFilter } from 'ark-ripple/locale';
import { Portal } from 'ark-ripple/portal';
import { ChevronsUpDown, X } from 'lucide-ripple';
import styles from 'styles/combobox.module.css';

export component HighlightMatchingText() {
  const filterApi = useFilter({ sensitivity: 'base' });

  let { collection, filter } = useListCollection(
    {
      initialItems: [
        { label: 'John Smith', value: 'john-smith' },
        { label: 'Jane Doe', value: 'jane-doe' },
        { label: 'Bob Johnson', value: 'bob-johnson' },
        { label: 'Alice Williams', value: 'alice-williams' },
        { label: 'Charlie Brown', value: 'charlie-brown' },
        { label: 'Diana Ross', value: 'diana-ross' },
      ],
      filter: @filterApi.contains,
    },
  );

  const handleInputChange = (details: Combobox.InputValueChangeDetails) => {
    filter(details.inputValue);
  };

  <Combobox.Root class={styles.Root} {collection} onInputValueChange={handleInputChange}>
    <Combobox.Label class={styles.Label}>{'Assignee'}</Combobox.Label>
    <Combobox.Control class={styles.Control}>
      <Combobox.Input class={styles.Input} placeholder="e.g. John Smith" />
      <div class={styles.Indicators}>
        <Combobox.ClearTrigger class={styles.ClearTrigger}>
          <X />
        </Combobox.ClearTrigger>
        <Combobox.Trigger class={styles.Trigger}>
          <ChevronsUpDown />
        </Combobox.Trigger>
      </div>
    </Combobox.Control>
    <Portal>
      <Combobox.Positioner>
        <Combobox.Content class={styles.Content}>
          for (const item of @collection.items; key item.value) {
            <Combobox.Item class={styles.Item} {item}>
              <Combobox.ItemText class={styles.ItemText}>
                <Combobox.Context>
                  component children({ context }) {
                    <Highlight text={item.label} query={@context.inputValue} ignoreCase />
                  }
                </Combobox.Context>
              </Combobox.ItemText>
            </Combobox.Item>
          }
        </Combobox.Content>
      </Combobox.Positioner>
    </Portal>
  </Combobox.Root>
}

```

### Dynamic

Generate combobox items dynamically based on user input. This is useful for creating suggestions or autocomplete
functionality.

**Example: dynamic**

```ripple
import { Combobox, useListCollection } from 'ark-ripple/combobox';
import { Portal } from 'ark-ripple/portal';
import { Check, ChevronsUpDown } from 'lucide-ripple';
import styles from 'styles/combobox.module.css';

const suggestList = ['gmail.com', 'yahoo.com', 'ark-ui.rip'];

export component Dynamic() {
  let { collection, set } = useListCollection<string>(
    {
      initialItems: [],
    },
  );

  const handleInputChange = (details: Combobox.InputValueChangeDetails) => {
    if (details.reason === 'input-change') {
      const items = suggestList.map((item) => `${details.inputValue}@${item}`);
      set(items);
    }
  };

  <Combobox.Root class={styles.Root} {collection} onInputValueChange={handleInputChange}>
    <Combobox.Label class={styles.Label}>{'Email'}</Combobox.Label>
    <Combobox.Control class={styles.Control}>
      <Combobox.Input class={styles.Input} placeholder="e.g. john" />
      <div class={styles.Indicators}>
        <Combobox.Trigger class={styles.Trigger}>
          <ChevronsUpDown />
        </Combobox.Trigger>
      </div>
    </Combobox.Control>
    <Portal>
      <Combobox.Positioner>
        <Combobox.Content class={styles.Content}>
          for (const item of @collection.items; key item) {
            <Combobox.Item class={styles.Item} {item}>
              <Combobox.ItemText class={styles.ItemText}>{item}</Combobox.ItemText>
              <Combobox.ItemIndicator class={styles.ItemIndicator}>
                <Check />
              </Combobox.ItemIndicator>
            </Combobox.Item>
          }
        </Combobox.Content>
      </Combobox.Positioner>
    </Portal>
  </Combobox.Root>
}

```

### Creatable

Allow users to create new options when their search doesn't match any existing items. This is useful for tags,
categories, or other custom values.

**Example: creatable**

```ripple
import { Combobox, useListCollection } from 'ark-ripple/combobox';
import { useFilter } from 'ark-ripple/locale';
import { Portal } from 'ark-ripple/portal';
import { Check, ChevronsUpDown, X } from 'lucide-ripple';
import styles from 'styles/combobox.module.css';

interface Item {
  label: string;
  value: string;
  __new__?: boolean | undefined;
}

const NEW_OPTION_VALUE = '[[new]]';
const createNewOption = (value: string): Item => ({ label: value, value: NEW_OPTION_VALUE });
const isNewOptionValue = (value: string) => value === NEW_OPTION_VALUE;
const replaceNewOptionValue = (values: string[], value: string) => values.map(
  (v) => (v === NEW_OPTION_VALUE ? value : v),
);
const getNewOptionData = (inputValue: string): Item => ({
  label: inputValue,
  value: inputValue,
  __new__: true,
});

export component Creatable() {
  const filterApi = useFilter({ sensitivity: 'base' });

  let { collection, filter, upsert, remove, update } = useListCollection<Item>(
    {
      initialItems: [
        { label: 'Bug', value: 'bug' },
        { label: 'Feature', value: 'feature' },
        { label: 'Enhancement', value: 'enhancement' },
        { label: 'Documentation', value: 'docs' },
      ],
      filter: @filterApi.contains,
    },
  );

  const isValidNewOption = (inputValue: string) => {
    const exactOptionMatch =
      @collection.filter((item) => item.toLowerCase() === inputValue.toLowerCase()).size > 0;
    return !exactOptionMatch && inputValue.trim().length > 0;
  };

  let selectedValue = track<string[]>([]);
  let inputValue = track('');

  <Combobox.Root
    class={styles.Root}
    {collection}
    value={selectedValue}
    allowCustomValue
    onInputValueChange={(details) => {
      if (details.reason === 'input-change' || details.reason === 'item-select') {
        if (isValidNewOption(details.inputValue)) {
          upsert(NEW_OPTION_VALUE, createNewOption(details.inputValue));
        } else if (details.inputValue.trim().length === 0) {
          remove(NEW_OPTION_VALUE);
        }
        filter(details.inputValue);
      }
      @inputValue = details.inputValue;
    }}
    onOpenChange={(details) => {
      if (details.reason === 'trigger-click') {
        filter('');
      }
    }}
    onValueChange={(details) => {
      @selectedValue = replaceNewOptionValue(details.value, @inputValue);
      if (details.value.includes(NEW_OPTION_VALUE)) {
        update(NEW_OPTION_VALUE, getNewOptionData(@inputValue));
      }
    }}
  >
    <Combobox.Label class={styles.Label}>{'Label'}</Combobox.Label>
    <Combobox.Control class={styles.Control}>
      <Combobox.Input class={styles.Input} placeholder="e.g. Bug" />
      <div class={styles.Indicators}>
        <Combobox.ClearTrigger class={styles.ClearTrigger}>
          <X />
        </Combobox.ClearTrigger>
        <Combobox.Trigger class={styles.Trigger}>
          <ChevronsUpDown />
        </Combobox.Trigger>
      </div>
    </Combobox.Control>
    <Portal>
      <Combobox.Positioner>
        <Combobox.Content class={styles.Content}>
          for (const item of @collection.items; key item.value) {
            <Combobox.Item class={styles.Item} {item}>
              if (isNewOptionValue(item.value)) {
                <Combobox.ItemText class={styles.ItemText}>
                  {'+ Create "'}
                  {item.label}
                  {'"'}
                </Combobox.ItemText>
              } else {
                <Combobox.ItemText class={styles.ItemText}>
                  {item.label}
                  {item.__new__ ? ' (new)' : ''}
                </Combobox.ItemText>
              }
              <Combobox.ItemIndicator class={styles.ItemIndicator}>
                <Check />
              </Combobox.ItemIndicator>
            </Combobox.Item>
          }
        </Combobox.Content>
      </Combobox.Positioner>
    </Portal>
  </Combobox.Root>
}

```

### Multiple Selection

Enable multiple selection by setting the `multiple` prop. Selected items can be displayed as tags above the input.

**Example: multiple**

```ripple
import { Combobox, useListCollection } from 'ark-ripple/combobox';
import { useFilter } from 'ark-ripple/locale';
import { Portal } from 'ark-ripple/portal';
import { Check, ChevronsUpDown } from 'lucide-ripple';
import styles from 'styles/combobox.module.css';

export component Multiple() {
  const filterApi = useFilter({ sensitivity: 'base' });

  let { collection, filter, remove } = useListCollection(
    {
      initialItems: [
        { label: 'JavaScript', value: 'js' },
        { label: 'TypeScript', value: 'ts' },
        { label: 'Python', value: 'python' },
        { label: 'Go', value: 'go' },
        { label: 'Rust', value: 'rust' },
        { label: 'Java', value: 'java' },
      ],
      filter: @filterApi.contains,
    },
  );

  <Combobox.Root
    class={styles.Root}
    {collection}
    onInputValueChange={(details) => {
      filter(details.inputValue);
    }}
    onValueChange={(details) => {
      remove(...details.value);
    }}
    multiple
  >
    <Combobox.Label class={styles.Label}>{'Skills'}</Combobox.Label>
    <Combobox.Context>
      component children({ context }) {
        <div class={styles.Tags}>
          if (@context.selectedItems.length === 0) {
            <span class={styles.TagPlaceholder}>{'None selected'}</span>
          }
          for (const item of @context.selectedItems; key item.value) {
            <span class={styles.Tag}>{item.label}</span>
          }
        </div>
      }
    </Combobox.Context>
    <Combobox.Control class={styles.Control}>
      <Combobox.Input class={styles.Input} placeholder="e.g. JavaScript" />
      <div class={styles.Indicators}>
        <Combobox.Trigger class={styles.Trigger}>
          <ChevronsUpDown />
        </Combobox.Trigger>
      </div>
    </Combobox.Control>
    <Portal>
      <Combobox.Positioner>
        <Combobox.Content class={styles.Content}>
          <Combobox.Empty class={styles.Item}>{'No skills found'}</Combobox.Empty>
          for (const item of @collection.items; key item.value) {
            <Combobox.Item class={styles.Item} {item}>
              <Combobox.ItemText class={styles.ItemText}>{item.label}</Combobox.ItemText>
              <Combobox.ItemIndicator class={styles.ItemIndicator}>
                <Check />
              </Combobox.ItemIndicator>
            </Combobox.Item>
          }
        </Combobox.Content>
      </Combobox.Positioner>
    </Portal>
  </Combobox.Root>
}

```

### Async Search

Load options asynchronously based on user input using the `useAsyncList` hook. This is useful for searching large
datasets or fetching data from an API.

**Example: async-search**

```ripple
import { useAsyncList } from 'ark-ripple/collection';
import { Combobox, createListCollection } from 'ark-ripple/combobox';
import { Portal } from 'ark-ripple/portal';
import { Check, ChevronsUpDown, Loader, X } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/combobox.module.css';

interface Movie {
  id: string;
  title: string;
  year: number;
  director: string;
  genre: string;
}

export component AsyncSearch() {
  const list = useAsyncList<Movie>(
    {
      async load({ filterText, signal }: { filterText?: string; signal?: AbortSignal }) {
        if (!filterText) return { items: [] };

        await new Promise((resolve) => setTimeout(resolve, 300));

        if (signal?.aborted) return { items: [] };

        const items = allMovies.filter(
          (movie) => movie.title.toLowerCase().includes(filterText.toLowerCase()) ||
            movie.director.toLowerCase().includes(filterText.toLowerCase()) ||
            movie.genre.toLowerCase().includes(filterText.toLowerCase()),
        );

        return { items };
      },
    },
  );

  const collection = track(
    () => createListCollection(
      {
        items: @list.items,
        itemToString: (item) => item.title,
        itemToValue: (item) => item.id,
      },
    ),
  );

  <Combobox.Root
    class={styles.Root}
    {collection}
    onInputValueChange={(details) => {
      if (details.reason === 'input-change') {
        @list.setFilterText(details.inputValue);
      }
    }}
  >
    <Combobox.Label class={styles.Label}>{'Movie'}</Combobox.Label>
    <Combobox.Control class={styles.Control}>
      <Combobox.Input class={styles.Input} placeholder="e.g. Inception" />
      <div class={styles.Indicators}>
        <Combobox.ClearTrigger class={styles.ClearTrigger}>
          <X />
        </Combobox.ClearTrigger>
        <Combobox.Trigger class={styles.Trigger}>
          <ChevronsUpDown />
        </Combobox.Trigger>
      </div>
    </Combobox.Control>
    <Portal>
      <Combobox.Positioner>
        <Combobox.Content class={styles.Content}>
          if (@list.loading) {
            <div class={styles.Status}>
              <Loader class={styles.Spinner} />
              <span>{'Searching...'}</span>
            </div>
          } else if (@list.error) {
            <div class={styles.Status}>{@list.error.message}</div>
          } else if (@list.items.length === 0) {
            <div class={styles.Status}>
              {@list.filterText ? 'No results found' : 'Start typing to search movies...'}
            </div>
          } else {
            for (const movie of @list.items; key movie.id) {
              <Combobox.Item class={styles.Item} item={movie}>
                <Combobox.ItemText class={styles.ItemText}>
                  <span class={styles.ItemTitle}>{movie.title}</span>
                  <span class={styles.ItemSubtitle}>
                    {movie.year}
                    {' · '}
                    {movie.director}
                  </span>
                </Combobox.ItemText>
                <Combobox.ItemIndicator class={styles.ItemIndicator}>
                  <Check />
                </Combobox.ItemIndicator>
              </Combobox.Item>
            }
          }
        </Combobox.Content>
      </Combobox.Positioner>
    </Portal>
  </Combobox.Root>
}

const allMovies: Movie[] = [
  {
    id: 'inception',
    title: 'Inception',
    year: 2010,
    director: 'Christopher Nolan',
    genre: 'Sci-Fi',
  },
  {
    id: 'the-dark-knight',
    title: 'The Dark Knight',
    year: 2008,
    director: 'Christopher Nolan',
    genre: 'Action',
  },
  {
    id: 'pulp-fiction',
    title: 'Pulp Fiction',
    year: 1994,
    director: 'Quentin Tarantino',
    genre: 'Crime',
  },
  {
    id: 'the-godfather',
    title: 'The Godfather',
    year: 1972,
    director: 'Francis Ford Coppola',
    genre: 'Crime',
  },
  {
    id: 'forrest-gump',
    title: 'Forrest Gump',
    year: 1994,
    director: 'Robert Zemeckis',
    genre: 'Drama',
  },
  {
    id: 'the-matrix',
    title: 'The Matrix',
    year: 1999,
    director: 'The Wachowskis',
    genre: 'Sci-Fi',
  },
  {
    id: 'interstellar',
    title: 'Interstellar',
    year: 2014,
    director: 'Christopher Nolan',
    genre: 'Sci-Fi',
  },
  { id: 'parasite', title: 'Parasite', year: 2019, director: 'Bong Joon-ho', genre: 'Thriller' },
  {
    id: 'the-shawshank-redemption',
    title: 'The Shawshank Redemption',
    year: 1994,
    director: 'Frank Darabont',
    genre: 'Drama',
  },
  { id: 'fight-club', title: 'Fight Club', year: 1999, director: 'David Fincher', genre: 'Drama' },
  {
    id: 'goodfellas',
    title: 'Goodfellas',
    year: 1990,
    director: 'Martin Scorsese',
    genre: 'Crime',
  },
  {
    id: 'the-silence-of-the-lambs',
    title: 'The Silence of the Lambs',
    year: 1991,
    director: 'Jonathan Demme',
    genre: 'Thriller',
  },
];

```

### Virtualized

For very large lists, use virtualization with `@tanstack/virtual` to render only the visible items. Pass the
`scrollToIndexFn` prop to enable keyboard navigation within the virtualized list.

**Example: virtualized**

```ripple
import { Combobox, useListCollection } from 'ark-ripple/combobox';
import { useFilter } from 'ark-ripple/locale';
import { Portal } from 'ark-ripple/portal';
import { Check, ChevronsUpDown } from 'lucide-ripple';
import styles from 'styles/combobox.module.css';
import { createVirtualizer } from '../../../utils/use-virtualizer.ripple';
import { flushSync, track } from 'ripple';

export component Virtualized() {
  let contentRef = track<HTMLDivElement | null>(null);

  const filterApi = useFilter({ sensitivity: 'base' });

  let { collection, filter, reset } = useListCollection(
    {
      initialItems: countries,
      filter: @filterApi.startsWith,
    },
  );

  const virtualizer = createVirtualizer(
    {
      get count() {
        return @collection.size;
      },
      getScrollElement: () => @contentRef,
      estimateSize: () => 32,
      overscan: 10,
    },
  );

  const handleScrollToIndex: Combobox.RootProps<Country>['scrollToIndexFn'] = (details) => {
    flushSync(() => {
      virtualizer.scrollToIndex(details.index, { align: 'center', behavior: 'auto' });
    });
  };

  const handleInputChange = (details: Combobox.InputValueChangeDetails) => {
    filter(details.inputValue);
  };

  <Combobox.Root
    class={styles.Root}
    {collection}
    onInputValueChange={handleInputChange}
    scrollToIndexFn={handleScrollToIndex}
  >
    <Combobox.Label class={styles.Label}>{'Country'}</Combobox.Label>
    <Combobox.Control class={styles.Control}>
      <Combobox.Input class={styles.Input} placeholder="e.g. Germany" />
      <div class={styles.Indicators}>
        <Combobox.Trigger class={styles.Trigger} onClick={reset}>
          <ChevronsUpDown />
        </Combobox.Trigger>
      </div>
    </Combobox.Control>
    <Portal>
      <Combobox.Positioner>
        <Combobox.Content class={styles.Content}>
          <div
            {ref (el: HTMLDivElement) => {
              @contentRef = el;
              return () => {
                @contentRef = null;
              };
            }}
            class={styles.Scroller}
          >
            <div
              style={{
                height: `${virtualizer.getTotalSize()}px`,
                width: '100%',
                position: 'relative',
              }}
            >
              for (const virtualItem of virtualizer.getVirtualItems(); key ((@collection.items[virtualItem.index])).value) {
                let item = @collection.items[virtualItem.index];
                <Combobox.Item
                  class={styles.Item}
                  {item}
                  aria-setsize={@collection.size}
                  aria-posinset={virtualItem.index + 1}
                  style={{
                    position: 'absolute',
                    top: '0',
                    left: '0',
                    width: '100%',
                    height: `${virtualItem.size}px`,
                    transform: `translateY(${virtualItem.start}px)`,
                  }}
                >
                  <Combobox.ItemText class={styles.ItemText}>
                    <span aria-hidden style={{ marginRight: '8px' }}>{item.emoji}</span>
                    {item.label}
                  </Combobox.ItemText>
                  <Combobox.ItemIndicator class={styles.ItemIndicator}>
                    <Check />
                  </Combobox.ItemIndicator>
                </Combobox.Item>
              }
            </div>
          </div>
        </Combobox.Content>
      </Combobox.Positioner>
    </Portal>
  </Combobox.Root>
}

interface Country {
  value: string;
  label: string;
  emoji: string;
}

const countries: Country[] = [
  { value: 'AD', label: 'Andorra', emoji: '🇦🇩' },
  { value: 'AE', label: 'United Arab Emirates', emoji: '🇦🇪' },
  { value: 'AF', label: 'Afghanistan', emoji: '🇦🇫' },
  { value: 'AG', label: 'Antigua and Barbuda', emoji: '🇦🇬' },
  { value: 'AI', label: 'Anguilla', emoji: '🇦🇮' },
  { value: 'AL', label: 'Albania', emoji: '🇦🇱' },
  { value: 'AM', label: 'Armenia', emoji: '🇦🇲' },
  { value: 'AO', label: 'Angola', emoji: '🇦🇴' },
  { value: 'AQ', label: 'Antarctica', emoji: '🇦🇶' },
  { value: 'AR', label: 'Argentina', emoji: '🇦🇷' },
  { value: 'AS', label: 'American Samoa', emoji: '🇦🇸' },
  { value: 'AT', label: 'Austria', emoji: '🇦🇹' },
  { value: 'AU', label: 'Australia', emoji: '🇦🇺' },
  { value: 'AW', label: 'Aruba', emoji: '🇦🇼' },
  { value: 'AX', label: 'Åland Islands', emoji: '🇦🇽' },
  { value: 'AZ', label: 'Azerbaijan', emoji: '🇦🇿' },
  { value: 'BA', label: 'Bosnia and Herzegovina', emoji: '🇧🇦' },
  { value: 'BB', label: 'Barbados', emoji: '🇧🇧' },
  { value: 'BD', label: 'Bangladesh', emoji: '🇧🇩' },
  { value: 'BE', label: 'Belgium', emoji: '🇧🇪' },
  { value: 'BF', label: 'Burkina Faso', emoji: '🇧🇫' },
  { value: 'BG', label: 'Bulgaria', emoji: '🇧🇬' },
  { value: 'BH', label: 'Bahrain', emoji: '🇧🇭' },
  { value: 'BI', label: 'Burundi', emoji: '🇧🇮' },
  { value: 'BJ', label: 'Benin', emoji: '🇧🇯' },
  { value: 'BL', label: 'Saint Barthélemy', emoji: '🇧🇱' },
  { value: 'BM', label: 'Bermuda', emoji: '🇧🇲' },
  { value: 'BN', label: 'Brunei', emoji: '🇧🇳' },
  { value: 'BO', label: 'Bolivia', emoji: '🇧🇴' },
  { value: 'BR', label: 'Brazil', emoji: '🇧🇷' },
  { value: 'BS', label: 'Bahamas', emoji: '🇧🇸' },
  { value: 'BT', label: 'Bhutan', emoji: '🇧🇹' },
  { value: 'BW', label: 'Botswana', emoji: '🇧🇼' },
  { value: 'BY', label: 'Belarus', emoji: '🇧🇾' },
  { value: 'BZ', label: 'Belize', emoji: '🇧🇿' },
  { value: 'CA', label: 'Canada', emoji: '🇨🇦' },
  { value: 'CD', label: 'Congo', emoji: '🇨🇩' },
  { value: 'CF', label: 'Central African Republic', emoji: '🇨🇫' },
  { value: 'CH', label: 'Switzerland', emoji: '🇨🇭' },
  { value: 'CI', label: 'Côte d\'Ivoire', emoji: '🇨🇮' },
  { value: 'CK', label: 'Cook Islands', emoji: '🇨🇰' },
  { value: 'CL', label: 'Chile', emoji: '🇨🇱' },
  { value: 'CM', label: 'Cameroon', emoji: '🇨🇲' },
  { value: 'CN', label: 'China', emoji: '🇨🇳' },
  { value: 'CO', label: 'Colombia', emoji: '🇨🇴' },
  { value: 'CR', label: 'Costa Rica', emoji: '🇨🇷' },
  { value: 'CU', label: 'Cuba', emoji: '🇨🇺' },
  { value: 'CV', label: 'Cabo Verde', emoji: '🇨🇻' },
  { value: 'CY', label: 'Cyprus', emoji: '🇨🇾' },
  { value: 'CZ', label: 'Czech Republic', emoji: '🇨🇿' },
  { value: 'DE', label: 'Germany', emoji: '🇩🇪' },
  { value: 'DJ', label: 'Djibouti', emoji: '🇩🇯' },
  { value: 'DK', label: 'Denmark', emoji: '🇩🇰' },
  { value: 'DM', label: 'Dominica', emoji: '🇩🇲' },
  { value: 'DO', label: 'Dominican Republic', emoji: '🇩🇴' },
  { value: 'DZ', label: 'Algeria', emoji: '🇩🇿' },
  { value: 'EC', label: 'Ecuador', emoji: '🇪🇨' },
  { value: 'EE', label: 'Estonia', emoji: '🇪🇪' },
  { value: 'EG', label: 'Egypt', emoji: '🇪🇬' },
  { value: 'ER', label: 'Eritrea', emoji: '🇪🇷' },
  { value: 'ES', label: 'Spain', emoji: '🇪🇸' },
  { value: 'ET', label: 'Ethiopia', emoji: '🇪🇹' },
  { value: 'FI', label: 'Finland', emoji: '🇫🇮' },
  { value: 'FJ', label: 'Fiji', emoji: '🇫🇯' },
  { value: 'FK', label: 'Falkland Islands', emoji: '🇫🇰' },
  { value: 'FM', label: 'Micronesia', emoji: '🇫🇲' },
  { value: 'FO', label: 'Faroe Islands', emoji: '🇫🇴' },
  { value: 'FR', label: 'France', emoji: '🇫🇷' },
  { value: 'GA', label: 'Gabon', emoji: '🇬🇦' },
  { value: 'GB', label: 'United Kingdom', emoji: '🇬🇧' },
  { value: 'GD', label: 'Grenada', emoji: '🇬🇩' },
  { value: 'GE', label: 'Georgia', emoji: '🇬🇪' },
  { value: 'GH', label: 'Ghana', emoji: '🇬🇭' },
  { value: 'GI', label: 'Gibraltar', emoji: '🇬🇮' },
  { value: 'GL', label: 'Greenland', emoji: '🇬🇱' },
  { value: 'GM', label: 'Gambia', emoji: '🇬🇲' },
  { value: 'GN', label: 'Guinea', emoji: '🇬🇳' },
  { value: 'GQ', label: 'Equatorial Guinea', emoji: '🇬🇶' },
  { value: 'GR', label: 'Greece', emoji: '🇬🇷' },
  { value: 'GT', label: 'Guatemala', emoji: '🇬🇹' },
  { value: 'GU', label: 'Guam', emoji: '🇬🇺' },
  { value: 'GW', label: 'Guinea-Bissau', emoji: '🇬🇼' },
  { value: 'GY', label: 'Guyana', emoji: '🇬🇾' },
  { value: 'HK', label: 'Hong Kong', emoji: '🇭🇰' },
  { value: 'HN', label: 'Honduras', emoji: '🇭🇳' },
  { value: 'HR', label: 'Croatia', emoji: '🇭🇷' },
  { value: 'HT', label: 'Haiti', emoji: '🇭🇹' },
  { value: 'HU', label: 'Hungary', emoji: '🇭🇺' },
  { value: 'ID', label: 'Indonesia', emoji: '🇮🇩' },
  { value: 'IE', label: 'Ireland', emoji: '🇮🇪' },
  { value: 'IL', label: 'Israel', emoji: '🇮🇱' },
  { value: 'IM', label: 'Isle of Man', emoji: '🇮🇲' },
  { value: 'IN', label: 'India', emoji: '🇮🇳' },
  { value: 'IQ', label: 'Iraq', emoji: '🇮🇶' },
  { value: 'IR', label: 'Iran', emoji: '🇮🇷' },
  { value: 'IS', label: 'Iceland', emoji: '🇮🇸' },
  { value: 'IT', label: 'Italy', emoji: '🇮🇹' },
  { value: 'JE', label: 'Jersey', emoji: '🇯🇪' },
  { value: 'JM', label: 'Jamaica', emoji: '🇯🇲' },
  { value: 'JO', label: 'Jordan', emoji: '🇯🇴' },
  { value: 'JP', label: 'Japan', emoji: '🇯🇵' },
  { value: 'KE', label: 'Kenya', emoji: '🇰🇪' },
  { value: 'KG', label: 'Kyrgyzstan', emoji: '🇰🇬' },
  { value: 'KH', label: 'Cambodia', emoji: '🇰🇭' },
  { value: 'KI', label: 'Kiribati', emoji: '🇰🇮' },
  { value: 'KM', label: 'Comoros', emoji: '🇰🇲' },
  { value: 'KN', label: 'Saint Kitts and Nevis', emoji: '🇰🇳' },
  { value: 'KP', label: 'North Korea', emoji: '🇰🇵' },
  { value: 'KR', label: 'South Korea', emoji: '🇰🇷' },
  { value: 'KW', label: 'Kuwait', emoji: '🇰🇼' },
  { value: 'KY', label: 'Cayman Islands', emoji: '🇰🇾' },
  { value: 'KZ', label: 'Kazakhstan', emoji: '🇰🇿' },
  { value: 'LA', label: 'Laos', emoji: '🇱🇦' },
  { value: 'LB', label: 'Lebanon', emoji: '🇱🇧' },
  { value: 'LC', label: 'Saint Lucia', emoji: '🇱🇨' },
  { value: 'LI', label: 'Liechtenstein', emoji: '🇱🇮' },
  { value: 'LK', label: 'Sri Lanka', emoji: '🇱🇰' },
  { value: 'LR', label: 'Liberia', emoji: '🇱🇷' },
  { value: 'LS', label: 'Lesotho', emoji: '🇱🇸' },
  { value: 'LT', label: 'Lithuania', emoji: '🇱🇹' },
  { value: 'LU', label: 'Luxembourg', emoji: '🇱🇺' },
  { value: 'LV', label: 'Latvia', emoji: '🇱🇻' },
  { value: 'LY', label: 'Libya', emoji: '🇱🇾' },
  { value: 'MA', label: 'Morocco', emoji: '🇲🇦' },
  { value: 'MC', label: 'Monaco', emoji: '🇲🇨' },
  { value: 'MD', label: 'Moldova', emoji: '🇲🇩' },
  { value: 'ME', label: 'Montenegro', emoji: '🇲🇪' },
  { value: 'MG', label: 'Madagascar', emoji: '🇲🇬' },
  { value: 'MH', label: 'Marshall Islands', emoji: '🇲🇭' },
  { value: 'MK', label: 'North Macedonia', emoji: '🇲🇰' },
  { value: 'ML', label: 'Mali', emoji: '🇲🇱' },
  { value: 'MM', label: 'Myanmar', emoji: '🇲🇲' },
  { value: 'MN', label: 'Mongolia', emoji: '🇲🇳' },
  { value: 'MO', label: 'Macao', emoji: '🇲🇴' },
  { value: 'MR', label: 'Mauritania', emoji: '🇲🇷' },
  { value: 'MS', label: 'Montserrat', emoji: '🇲🇸' },
  { value: 'MT', label: 'Malta', emoji: '🇲🇹' },
  { value: 'MU', label: 'Mauritius', emoji: '🇲🇺' },
  { value: 'MV', label: 'Maldives', emoji: '🇲🇻' },
  { value: 'MW', label: 'Malawi', emoji: '🇲🇼' },
  { value: 'MX', label: 'Mexico', emoji: '🇲🇽' },
  { value: 'MY', label: 'Malaysia', emoji: '🇲🇾' },
  { value: 'MZ', label: 'Mozambique', emoji: '🇲🇿' },
  { value: 'NA', label: 'Namibia', emoji: '🇳🇦' },
  { value: 'NC', label: 'New Caledonia', emoji: '🇳🇨' },
  { value: 'NE', label: 'Niger', emoji: '🇳🇪' },
  { value: 'NF', label: 'Norfolk Island', emoji: '🇳🇫' },
  { value: 'NG', label: 'Nigeria', emoji: '🇳🇬' },
  { value: 'NI', label: 'Nicaragua', emoji: '🇳🇮' },
  { value: 'NL', label: 'Netherlands', emoji: '🇳🇱' },
  { value: 'NO', label: 'Norway', emoji: '🇳🇴' },
  { value: 'NP', label: 'Nepal', emoji: '🇳🇵' },
  { value: 'NR', label: 'Nauru', emoji: '🇳🇷' },
  { value: 'NU', label: 'Niue', emoji: '🇳🇺' },
  { value: 'NZ', label: 'New Zealand', emoji: '🇳🇿' },
  { value: 'OM', label: 'Oman', emoji: '🇴🇲' },
  { value: 'PA', label: 'Panama', emoji: '🇵🇦' },
  { value: 'PE', label: 'Peru', emoji: '🇵🇪' },
  { value: 'PF', label: 'French Polynesia', emoji: '🇵🇫' },
  { value: 'PG', label: 'Papua New Guinea', emoji: '🇵🇬' },
  { value: 'PH', label: 'Philippines', emoji: '🇵🇭' },
  { value: 'PK', label: 'Pakistan', emoji: '🇵🇰' },
  { value: 'PL', label: 'Poland', emoji: '🇵🇱' },
  { value: 'PR', label: 'Puerto Rico', emoji: '🇵🇷' },
  { value: 'PS', label: 'Palestine', emoji: '🇵🇸' },
  { value: 'PT', label: 'Portugal', emoji: '🇵🇹' },
  { value: 'PW', label: 'Palau', emoji: '🇵🇼' },
  { value: 'PY', label: 'Paraguay', emoji: '🇵🇾' },
  { value: 'QA', label: 'Qatar', emoji: '🇶🇦' },
  { value: 'RO', label: 'Romania', emoji: '🇷🇴' },
  { value: 'RS', label: 'Serbia', emoji: '🇷🇸' },
  { value: 'RU', label: 'Russia', emoji: '🇷🇺' },
  { value: 'RW', label: 'Rwanda', emoji: '🇷🇼' },
  { value: 'SA', label: 'Saudi Arabia', emoji: '🇸🇦' },
  { value: 'SB', label: 'Solomon Islands', emoji: '🇸🇧' },
  { value: 'SC', label: 'Seychelles', emoji: '🇸🇨' },
  { value: 'SD', label: 'Sudan', emoji: '🇸🇩' },
  { value: 'SE', label: 'Sweden', emoji: '🇸🇪' },
  { value: 'SG', label: 'Singapore', emoji: '🇸🇬' },
  { value: 'SI', label: 'Slovenia', emoji: '🇸🇮' },
  { value: 'SK', label: 'Slovakia', emoji: '🇸🇰' },
  { value: 'SL', label: 'Sierra Leone', emoji: '🇸🇱' },
  { value: 'SM', label: 'San Marino', emoji: '🇸🇲' },
  { value: 'SN', label: 'Senegal', emoji: '🇸🇳' },
  { value: 'SO', label: 'Somalia', emoji: '🇸🇴' },
  { value: 'SR', label: 'Suriname', emoji: '🇸🇷' },
  { value: 'SS', label: 'South Sudan', emoji: '🇸🇸' },
  { value: 'ST', label: 'Sao Tome and Principe', emoji: '🇸🇹' },
  { value: 'SV', label: 'El Salvador', emoji: '🇸🇻' },
  { value: 'SY', label: 'Syria', emoji: '🇸🇾' },
  { value: 'SZ', label: 'Eswatini', emoji: '🇸🇿' },
  { value: 'TC', label: 'Turks and Caicos Islands', emoji: '🇹🇨' },
  { value: 'TD', label: 'Chad', emoji: '🇹🇩' },
  { value: 'TG', label: 'Togo', emoji: '🇹🇬' },
  { value: 'TH', label: 'Thailand', emoji: '🇹🇭' },
  { value: 'TJ', label: 'Tajikistan', emoji: '🇹🇯' },
  { value: 'TK', label: 'Tokelau', emoji: '🇹🇰' },
  { value: 'TL', label: 'Timor-Leste', emoji: '🇹🇱' },
  { value: 'TM', label: 'Turkmenistan', emoji: '🇹🇲' },
  { value: 'TN', label: 'Tunisia', emoji: '🇹🇳' },
  { value: 'TO', label: 'Tonga', emoji: '🇹🇴' },
  { value: 'TR', label: 'Türkiye', emoji: '🇹🇷' },
  { value: 'TT', label: 'Trinidad and Tobago', emoji: '🇹🇹' },
  { value: 'TV', label: 'Tuvalu', emoji: '🇹🇻' },
  { value: 'TW', label: 'Taiwan', emoji: '🇹🇼' },
  { value: 'TZ', label: 'Tanzania', emoji: '🇹🇿' },
  { value: 'UA', label: 'Ukraine', emoji: '🇺🇦' },
  { value: 'UG', label: 'Uganda', emoji: '🇺🇬' },
  { value: 'US', label: 'United States', emoji: '🇺🇸' },
  { value: 'UY', label: 'Uruguay', emoji: '🇺🇾' },
  { value: 'UZ', label: 'Uzbekistan', emoji: '🇺🇿' },
  { value: 'VA', label: 'Vatican City', emoji: '🇻🇦' },
  { value: 'VC', label: 'Saint Vincent and the Grenadines', emoji: '🇻🇨' },
  { value: 'VE', label: 'Venezuela', emoji: '🇻🇪' },
  { value: 'VG', label: 'British Virgin Islands', emoji: '🇻🇬' },
  { value: 'VI', label: 'U.S. Virgin Islands', emoji: '🇻🇮' },
  { value: 'VN', label: 'Vietnam', emoji: '🇻🇳' },
  { value: 'VU', label: 'Vanuatu', emoji: '🇻🇺' },
  { value: 'WF', label: 'Wallis and Futuna', emoji: '🇼🇫' },
  { value: 'WS', label: 'Samoa', emoji: '🇼🇸' },
  { value: 'YE', label: 'Yemen', emoji: '🇾🇪' },
  { value: 'YT', label: 'Mayotte', emoji: '🇾🇹' },
  { value: 'ZA', label: 'South Africa', emoji: '🇿🇦' },
  { value: 'ZM', label: 'Zambia', emoji: '🇿🇲' },
  { value: 'ZW', label: 'Zimbabwe', emoji: '🇿🇼' },
];

```

### Custom Object

Use the `itemToString` and `itemToValue` props to map custom objects to the required interface.

**Example: custom-object**

```ripple
import { Combobox, useListCollection } from 'ark-ripple/combobox';
import { useFilter } from 'ark-ripple/locale';
import { Portal } from 'ark-ripple/portal';
import { Check, ChevronsUpDown, X } from 'lucide-ripple';
import styles from 'styles/combobox.module.css';

export component CustomObject() {
  const filterApi = useFilter({ sensitivity: 'base' });

  let { collection, filter } = useListCollection(
    {
      initialItems: [
        { country: 'United States', code: 'US', flag: '🇺🇸' },
        { country: 'Canada', code: 'CA', flag: '🇨🇦' },
        { country: 'Australia', code: 'AU', flag: '🇦🇺' },
      ],
      itemToString: (item) => item.country,
      itemToValue: (item) => item.code,
      filter: @filterApi.contains,
    },
  );

  const handleInputChange = (details: Combobox.InputValueChangeDetails) => {
    filter(details.inputValue);
  };

  <Combobox.Root class={styles.Root} {collection} onInputValueChange={handleInputChange}>
    <Combobox.Label class={styles.Label}>{'Country'}</Combobox.Label>
    <Combobox.Control class={styles.Control}>
      <Combobox.Input class={styles.Input} placeholder="e.g. Canada" />
      <div class={styles.Indicators}>
        <Combobox.ClearTrigger class={styles.ClearTrigger}>
          <X />
        </Combobox.ClearTrigger>
        <Combobox.Trigger class={styles.Trigger}>
          <ChevronsUpDown />
        </Combobox.Trigger>
      </div>
    </Combobox.Control>
    <Portal>
      <Combobox.Positioner>
        <Combobox.Content class={styles.Content}>
          for (const item of @collection.items; key item.code) {
            <Combobox.Item class={styles.Item} {item}>
              <Combobox.ItemText class={styles.ItemText}>
                {item.flag}
                {' '}
                {item.country}
              </Combobox.ItemText>
              <Combobox.ItemIndicator class={styles.ItemIndicator}>
                <Check />
              </Combobox.ItemIndicator>
            </Combobox.Item>
          }
        </Combobox.Content>
      </Combobox.Positioner>
    </Portal>
  </Combobox.Root>
}

```

### Limit Results

Use the `limit` property on `useListCollection` to limit the number of rendered items in the DOM.

**Example: limit-results**

```ripple
import { Combobox, useListCollection } from 'ark-ripple/combobox';
import { useFilter } from 'ark-ripple/locale';
import { Portal } from 'ark-ripple/portal';
import { Check, ChevronsUpDown } from 'lucide-ripple';
import styles from 'styles/combobox.module.css';

const cities = [
  { label: 'New York', value: 'new-york' },
  { label: 'Los Angeles', value: 'los-angeles' },
  { label: 'Chicago', value: 'chicago' },
  { label: 'Houston', value: 'houston' },
  { label: 'Phoenix', value: 'phoenix' },
  { label: 'Philadelphia', value: 'philadelphia' },
  { label: 'San Antonio', value: 'san-antonio' },
  { label: 'San Diego', value: 'san-diego' },
  { label: 'Dallas', value: 'dallas' },
  { label: 'San Jose', value: 'san-jose' },
  { label: 'Austin', value: 'austin' },
  { label: 'Jacksonville', value: 'jacksonville' },
  { label: 'Fort Worth', value: 'fort-worth' },
  { label: 'Columbus', value: 'columbus' },
  { label: 'Charlotte', value: 'charlotte' },
  { label: 'San Francisco', value: 'san-francisco' },
  { label: 'Indianapolis', value: 'indianapolis' },
  { label: 'Seattle', value: 'seattle' },
  { label: 'Denver', value: 'denver' },
  { label: 'Boston', value: 'boston' },
];

export component LimitResults() {
  const filterApi = useFilter({ sensitivity: 'base' });

  let { collection, filter } = useListCollection(
    {
      initialItems: cities,
      limit: 5,
      filter: @filterApi.contains,
    },
  );

  const handleInputChange = (details: Combobox.InputValueChangeDetails) => {
    filter(details.inputValue);
  };

  <Combobox.Root class={styles.Root} {collection} onInputValueChange={handleInputChange}>
    <Combobox.Label class={styles.Label}>{'City'}</Combobox.Label>
    <Combobox.Control class={styles.Control}>
      <Combobox.Input class={styles.Input} placeholder="e.g. New York" />
      <div class={styles.Indicators}>
        <Combobox.Trigger class={styles.Trigger}>
          <ChevronsUpDown />
        </Combobox.Trigger>
      </div>
    </Combobox.Control>
    <Portal>
      <Combobox.Positioner>
        <Combobox.Content class={styles.Content}>
          for (const item of @collection.items; key item.value) {
            <Combobox.Item class={styles.Item} {item}>
              <Combobox.ItemText class={styles.ItemText}>{item.label}</Combobox.ItemText>
              <Combobox.ItemIndicator class={styles.ItemIndicator}>
                <Check />
              </Combobox.ItemIndicator>
            </Combobox.Item>
          }
        </Combobox.Content>
      </Combobox.Positioner>
    </Portal>
  </Combobox.Root>
}

```

## Guides

### Router Links

Customize the `navigate` prop on `Combobox.Root` to integrate with your router.:

```tsx
import { Combobox } from 'ark-ripple/combobox'
import { useNavigate } from '<some-router>'

function Demo() {
  const navigate = useNavigate()
  return (
    <Combobox.Root
      navigate={(e) => {
        navigate({ to: e.node.href })
      }}
    >
      {/* ... */}
    </Combobox.Root>
  )
}
```

### Custom Objects

By default, the combobox collection expects an array of objects with `label` and `value` properties. In some cases, you
may need to deal with custom objects.

Use the `itemToString` and `itemToValue` props to map the custom object to the required interface.

```tsx
const items = [
  { country: 'United States', code: 'US', flag: '🇺🇸' },
  { country: 'Canada', code: 'CA', flag: '🇨🇦' },
  { country: 'Australia', code: 'AU', flag: '🇦🇺' },
  // ...
]

const { collection } = useListCollection({
  initialItems: items,
  itemToString: (item) => item.country,
  itemToValue: (item) => item.code,
})
```

### Large Datasets

The recommended way of managing large lists is to use the `limit` property on the `useListCollection` hook. This will
limit the number of rendered items in the DOM to improve performance.

```tsx {3}
const { collection } = useListCollection({
  initialItems: items,
  limit: 10,
})
```

### Available Size

The following css variables are exposed to the `Combobox.Positioner` which you can use to style the `Combobox.Content`

```css
/* width of the combobox control */
--reference-width: <pixel-value>;
/* width of the available viewport */
--available-width: <pixel-value>;
/* height of the available viewport */
--available-height: <pixel-value>;
```

For example, if you want to make sure the maximum height doesn't exceed the available height, you can use the following:

```css
[data-scope='combobox'][data-part='content'] {
  max-height: calc(var(--available-height) - 100px);
}
```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `collection` | `ListCollection<T>` | Yes | The collection of items |
| `allowCustomValue` | `boolean` | No | Whether to allow typing custom values in the input |
| `alwaysSubmitOnEnter` | `boolean` | No | Whether to always submit on Enter key press, even if popup is open.
Useful for single-field autocomplete forms where Enter should submit the form. |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `autoFocus` | `boolean` | No | Whether to autofocus the input on mount |
| `closeOnSelect` | `boolean` | No | Whether to close the combobox when an item is selected. |
| `composite` | `boolean` | No | Whether the combobox is a composed with other composite widgets like tabs |
| `defaultHighlightedValue` | `string` | No | The initial highlighted value of the combobox when rendered.
Use when you don't need to control the highlighted value of the combobox. |
| `defaultInputValue` | `string` | No | The initial value of the combobox's input when rendered.
Use when you don't need to control the value of the combobox's input. |
| `defaultOpen` | `boolean` | No | The initial open state of the combobox when rendered.
Use when you don't need to control the open state of the combobox. |
| `defaultValue` | `string[]` | No | The initial value of the combobox's selected items when rendered.
Use when you don't need to control the value of the combobox's selected items. |
| `disabled` | `boolean` | No | Whether the combobox is disabled |
| `disableLayer` | `boolean` | No | Whether to disable registering this a dismissable layer |
| `form` | `string` | No | The associate form of the combobox. |
| `highlightedValue` | `string` | No | The controlled highlighted value of the combobox |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{
  root: string
  label: string
  control: string
  input: string
  content: string
  trigger: string
  clearTrigger: string
  item: (id: string, index?: number | undefined) => string
  positioner: string
  itemGroup: (id: string | number) => string
  itemGroupLabel: (id: string | number) => string
}>` | No | The ids of the elements in the combobox. Useful for composition. |
| `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame |
| `inputBehavior` | `'none' | 'autohighlight' | 'autocomplete'` | No | Defines the auto-completion behavior of the combobox.

- `autohighlight`: The first focused item is highlighted as the user types
- `autocomplete`: Navigating the listbox with the arrow keys selects the item and the input is updated |
| `inputValue` | `string` | No | The controlled value of the combobox's input |
| `invalid` | `boolean` | No | Whether the combobox is invalid |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `loopFocus` | `boolean` | No | Whether to loop the keyboard navigation through the items |
| `multiple` | `boolean` | No | Whether to allow multiple selection.

**Good to know:** When `multiple` is `true`, the `selectionBehavior` is automatically set to `clear`.
It is recommended to render the selected items in a separate container. |
| `name` | `string` | No | The `name` attribute of the combobox's input. Useful for form submission |
| `navigate` | `(details: NavigateDetails) => void` | No | Function to navigate to the selected item |
| `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state |
| `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component |
| `onHighlightChange` | `(details: HighlightChangeDetails<T>) => void` | No | Function called when an item is highlighted using the pointer
or keyboard navigation. |
| `onInputValueChange` | `(details: InputValueChangeDetails) => void` | No | Function called when the input's value changes |
| `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component |
| `onOpenChange` | `(details: OpenChangeDetails) => void` | No | Function called when the popup is opened |
| `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component |
| `onSelect` | `(details: SelectionDetails) => void` | No | Function called when an item is selected |
| `onValueChange` | `(details: ValueChangeDetails<T>) => void` | No | Function called when a new item is selected |
| `open` | `boolean` | No | The controlled open state of the combobox |
| `openOnChange` | `boolean | ((details: InputValueChangeDetails) => boolean)` | No | Whether to show the combobox when the input value changes |
| `openOnClick` | `boolean` | No | Whether to open the combobox popup on initial click on the input |
| `openOnKeyPress` | `boolean` | No | Whether to open the combobox on arrow key press |
| `placeholder` | `string` | No | The placeholder text of the combobox's input |
| `positioning` | `PositioningOptions` | No | The positioning options to dynamically position the menu |
| `present` | `boolean` | No | Whether the node is present (controlled by the user) |
| `readOnly` | `boolean` | No | Whether the combobox is readonly. This puts the combobox in a "non-editable" mode
but the user can still interact with it |
| `required` | `boolean` | No | Whether the combobox is required |
| `scrollToIndexFn` | `(details: ScrollToIndexDetails) => void` | No | Function to scroll to a specific index |
| `selectionBehavior` | `'clear' | 'replace' | 'preserve'` | No | The behavior of the combobox input when an item is selected

- `replace`: The selected item string is set as the input value
- `clear`: The input value is cleared
- `preserve`: The input value is preserved |
| `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. |
| `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |
| `value` | `string[]` | No | The controlled value of the combobox's selected items |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | combobox |
| `[data-part]` | root |
| `[data-invalid]` | Present when invalid |
| `[data-readonly]` | Present when read-only |


**ClearTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ClearTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | combobox |
| `[data-part]` | clear-trigger |
| `[data-invalid]` | Present when invalid |


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | combobox |
| `[data-part]` | content |
| `[data-state]` | "open" | "closed" |
| `[data-nested]` | listbox |
| `[data-has-nested]` | listbox |
| `[data-placement]` | The placement of the content |
| `[data-empty]` | Present when the content is empty |


**Content CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--layer-index` | The index of the dismissable in the layer stack |
| `--nested-layer-count` | The number of nested comboboxs |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | combobox |
| `[data-part]` | control |
| `[data-state]` | "open" | "closed" |
| `[data-focus]` | Present when focused |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]` | Present when invalid |


**Empty Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Input Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Input Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | combobox |
| `[data-part]` | input |
| `[data-invalid]` | Present when invalid |
| `[data-autofocus]` |  |
| `[data-state]` | "open" | "closed" |


**ItemGroupLabel Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemGroup Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemGroup Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | combobox |
| `[data-part]` | item-group |
| `[data-empty]` | Present when the content is empty |


**ItemIndicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemIndicator Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | combobox |
| `[data-part]` | item-indicator |
| `[data-state]` | "checked" | "unchecked" |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `item` | `any` | No | The item to render |
| `persistFocus` | `boolean` | No | Whether hovering outside should clear the highlighted state |


**Item Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | combobox |
| `[data-part]` | item |
| `[data-highlighted]` | Present when highlighted |
| `[data-state]` | "checked" | "unchecked" |
| `[data-disabled]` | Present when disabled |
| `[data-value]` | The value of the item |


**ItemText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemText Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | combobox |
| `[data-part]` | item-text |
| `[data-state]` | "checked" | "unchecked" |
| `[data-disabled]` | Present when disabled |
| `[data-highlighted]` | Present when highlighted |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | combobox |
| `[data-part]` | label |
| `[data-readonly]` | Present when read-only |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]` | Present when invalid |
| `[data-required]` | Present when required |
| `[data-focus]` | Present when focused |


**List Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**List Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | combobox |
| `[data-part]` | list |
| `[data-empty]` | Present when the content is empty |


**Positioner Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Positioner CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--reference-width` | The width of the reference element |
| `--reference-height` | The height of the root |
| `--available-width` | The available width in viewport |
| `--available-height` | The available height in viewport |
| `--x` | The x position for transform |
| `--y` | The y position for transform |
| `--z-index` | The z-index value |
| `--transform-origin` | The transform origin for animations |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseComboboxReturn<T>` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state |
| `present` | `boolean` | No | Whether the node is present (controlled by the user) |
| `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


**Trigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `focusable` | `boolean` | No | Whether the trigger is focusable |


**Trigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | combobox |
| `[data-part]` | trigger |
| `[data-state]` | "open" | "closed" |
| `[data-invalid]` | Present when invalid |
| `[data-focusable]` |  |
| `[data-readonly]` | Present when read-only |
| `[data-disabled]` | Present when disabled |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `focused` | `boolean` | Whether the combobox is focused |
| `open` | `boolean` | Whether the combobox is open |
| `inputValue` | `string` | The value of the combobox input |
| `highlightedValue` | `string` | The value of the highlighted item |
| `highlightedItem` | `V` | The highlighted item |
| `setHighlightValue` | `(value: string) => void` | The value of the combobox input |
| `clearHighlightValue` | `VoidFunction` | Function to clear the highlighted value |
| `syncSelectedItems` | `VoidFunction` | Function to sync the selected items with the value.
Useful when `value` is updated from async sources. |
| `selectedItems` | `V[]` | The selected items |
| `hasSelectedItems` | `boolean` | Whether there's a selected item |
| `value` | `string[]` | The selected item keys |
| `valueAsString` | `string` | The string representation of the selected items |
| `selectValue` | `(value: string) => void` | Function to select a value |
| `setValue` | `(value: string[]) => void` | Function to set the value of the combobox |
| `clearValue` | `(value?: string) => void` | Function to clear the value of the combobox |
| `focus` | `VoidFunction` | Function to focus on the combobox input |
| `setInputValue` | `(value: string, reason?: InputValueChangeReason) => void` | Function to set the input value of the combobox |
| `getItemState` | `(props: ItemProps) => ItemState` | Returns the state of a combobox item |
| `setOpen` | `(open: boolean, reason?: OpenChangeReason) => void` | Function to open or close the combobox |
| `collection` | `ListCollection<V>` | Function to toggle the combobox |
| `reposition` | `(options?: Partial<PositioningOptions>) => void` | Function to set the positioning options |
| `multiple` | `boolean` | Whether the combobox allows multiple selections |
| `disabled` | `boolean` | Whether the combobox is disabled |


## Accessibility

Complies with the [Combobox WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).

### Keyboard Support

**`ArrowDown`**
Description: When the combobox is closed, opens the listbox and highlights to the first option.
When the combobox is open, moves focus to the next option.

**`ArrowUp`**
Description: When the combobox is closed, opens the listbox and highlights to the last option.
When the combobox is open, moves focus to the previous option.

**`Home`**
Description: When the combobox is open, moves focus to the first option.

**`End`**
Description: When the combobox is open, moves focus to the last option.

**`Escape`**
Description: Closes the listbox.

**`Enter`**
Description: Selects the highlighted option and closes the combobox.

**`Esc`**
Description: Closes the combobox


# Date Picker 



## Anatomy



```tsx
<DatePicker.Root>
  <DatePicker.Label />
  <DatePicker.Control>
    <DatePicker.Input />
    <DatePicker.Trigger />
    <DatePicker.ClearTrigger />
  </DatePicker.Control>
  <DatePicker.Positioner>
    <DatePicker.Content>
      <DatePicker.View>
        <DatePicker.ViewControl>
          <DatePicker.PrevTrigger />
          <DatePicker.ViewTrigger>
            <DatePicker.RangeText />
          </DatePicker.ViewTrigger>
          <DatePicker.NextTrigger />
        </DatePicker.ViewControl>
        <DatePicker.Table>
          <DatePicker.TableHead>
            <DatePicker.TableRow>
              <DatePicker.TableHeader />
            </DatePicker.TableRow>
          </DatePicker.TableHead>
          <DatePicker.TableBody>
            <DatePicker.TableRow>
              <DatePicker.TableCell>
                <DatePicker.TableCellTrigger />
              </DatePicker.TableCell>
            </DatePicker.TableRow>
          </DatePicker.TableBody>
        </DatePicker.Table>
      </DatePicker.View>
    </DatePicker.Content>
  </DatePicker.Positioner>
</DatePicker.Root>
```

## Examples

**Example: basic**

```ripple
import { DatePicker } from 'ark-ripple/date-picker';
import { Portal } from 'ark-ripple/portal';
import { Calendar, ChevronLeft, ChevronRight } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/date-picker.module.css';

export component Basic() {
  <DatePicker.Root class={styles.Root}>
    <DatePicker.Label class={styles.Label}>{'Label'}</DatePicker.Label>
    <DatePicker.Control class={styles.Control}>
      <DatePicker.Input class={styles.Input} />
      <DatePicker.Trigger class={button.Root}>
        <Calendar />
      </DatePicker.Trigger>
      <DatePicker.ClearTrigger class={button.Root}>{'Clear'}</DatePicker.ClearTrigger>
    </DatePicker.Control>
    <Portal>
      <DatePicker.Positioner>
        <DatePicker.Content class={styles.Content}>
          <DatePicker.View view="day" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableHead class={styles.TableHead}>
                    <DatePicker.TableRow class={styles.TableRow}>
                      for (const weekDay of @context.weekDays; key weekDay.short) {
                        <DatePicker.TableHeader class={styles.TableHeader}>
                          {weekDay.short}
                        </DatePicker.TableHeader>
                      }
                    </DatePicker.TableRow>
                  </DatePicker.TableHead>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const week of @context.weeks; key week[0].toString()) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const day of week; key day.toString()) {
                          <DatePicker.TableCell class={styles.TableCell} value={day}>
                            <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                              {day.day}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
          <DatePicker.View view="month" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const months of @context.getMonthsGrid(
                      { columns: 4, format: 'short' },
                    ); key months[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const month of months; key month.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={month.value}>
                            <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                              {month.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
          <DatePicker.View view="year" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const years of @context.getYearsGrid({ columns: 4 }); key years[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const year of years; key year.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={year.value}>
                            <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                              {year.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
        </DatePicker.Content>
      </DatePicker.Positioner>
    </Portal>
  </DatePicker.Root>
}

```

### Default Value

Use the `defaultValue` prop with `parseDate` to set the initial date value.

**Example: default-value**

```ripple
import { DatePicker, parseDate } from 'ark-ripple/date-picker';
import { Portal } from 'ark-ripple/portal';
import { Calendar, ChevronLeft, ChevronRight } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/date-picker.module.css';

export component DefaultValue() {
  <DatePicker.Root class={styles.Root} defaultValue={[parseDate('2024-01-01')]}>
    <DatePicker.Label class={styles.Label}>{'Label'}</DatePicker.Label>
    <DatePicker.Control class={styles.Control}>
      <DatePicker.Input class={styles.Input} />
      <DatePicker.Trigger class={button.Root}>
        <Calendar />
      </DatePicker.Trigger>
      <DatePicker.ClearTrigger class={button.Root}>{'Clear'}</DatePicker.ClearTrigger>
    </DatePicker.Control>
    <Portal>
      <DatePicker.Positioner>
        <DatePicker.Content class={styles.Content}>
          <DatePicker.View view="day" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableHead class={styles.TableHead}>
                    <DatePicker.TableRow class={styles.TableRow}>
                      for (const weekDay of @context.weekDays; key weekDay.short) {
                        <DatePicker.TableHeader class={styles.TableHeader}>
                          {weekDay.short}
                        </DatePicker.TableHeader>
                      }
                    </DatePicker.TableRow>
                  </DatePicker.TableHead>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const week of @context.weeks; key week[0].toString()) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const day of week; key day.toString()) {
                          <DatePicker.TableCell class={styles.TableCell} value={day}>
                            <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                              {day.day}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
          <DatePicker.View view="month" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const months of @context.getMonthsGrid(
                      { columns: 4, format: 'short' },
                    ); key months[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const month of months; key month.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={month.value}>
                            <DatePicker.TableCellTrigger class={styles.MonthTableCellTrigger}>
                              {month.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
          <DatePicker.View view="year" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const years of @context.getYearsGrid({ columns: 4 }); key years[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const year of years; key year.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={year.value}>
                            <DatePicker.TableCellTrigger class={styles.YearTableCellTrigger}>
                              {year.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
        </DatePicker.Content>
      </DatePicker.Positioner>
    </Portal>
  </DatePicker.Root>
}

```

### Controlled

Use the `value` and `onValueChange` props to control the date picker's value programmatically.

**Example: controlled**

```ripple
import { DatePicker, parseDate } from 'ark-ripple/date-picker';
import { Portal } from 'ark-ripple/portal';
import { Calendar, ChevronLeft, ChevronRight } from 'lucide-ripple';
import { track } from 'ripple';
import button from 'styles/button.module.css';
import styles from 'styles/date-picker.module.css';

export component Controlled() {
  let value = track([parseDate('2022-01-01')]);
  <DatePicker.Root
    class={styles.Root}
    {value}
    onValueChange={(e) => {
      @value = e.value;
    }}
  >
    <DatePicker.Label class={styles.Label}>{'Label'}</DatePicker.Label>
    <DatePicker.Control class={styles.Control}>
      <DatePicker.Input class={styles.Input} />
      <DatePicker.Trigger class={button.Root}>
        <Calendar />
      </DatePicker.Trigger>
      <DatePicker.ClearTrigger class={button.Root}>{'Clear'}</DatePicker.ClearTrigger>
    </DatePicker.Control>
    <Portal>
      <DatePicker.Positioner>
        <DatePicker.Content class={styles.Content}>
          <DatePicker.View view="day" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableHead class={styles.TableHead}>
                    <DatePicker.TableRow class={styles.TableRow}>
                      for (const weekDay of @context.weekDays; key weekDay.short) {
                        <DatePicker.TableHeader class={styles.TableHeader}>
                          {weekDay.short}
                        </DatePicker.TableHeader>
                      }
                    </DatePicker.TableRow>
                  </DatePicker.TableHead>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const week of @context.weeks; key week[0].toString()) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const day of week; key day.toString()) {
                          <DatePicker.TableCell class={styles.TableCell} value={day}>
                            <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                              {day.day}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
          <DatePicker.View view="month" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const months of @context.getMonthsGrid(
                      { columns: 4, format: 'short' },
                    ); key months[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const month of months; key month.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={month.value}>
                            <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                              {month.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
          <DatePicker.View view="year" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const years of @context.getYearsGrid({ columns: 4 }); key years[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const year of years; key year.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={year.value}>
                            <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                              {year.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
        </DatePicker.Content>
      </DatePicker.Positioner>
    </Portal>
  </DatePicker.Root>
}

```

### Root Provider

An alternative way to control the date picker is to use the `RootProvider` component and the `useDatePicker` hook. This
way you can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { DatePicker, useDatePicker } from 'ark-ripple/date-picker';
import { Portal } from 'ark-ripple/portal';
import { Calendar, ChevronLeft, ChevronRight } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/date-picker.module.css';

export component RootProvider() {
  const datePicker = useDatePicker();
  <div class="stack">
    <button
      class={button.Root}
      onClick={() => {
        datePicker.clearValue();
      }}
    >
      {'Clear'}
    </button>
    <DatePicker.RootProvider value={datePicker}>
      <DatePicker.Label class={styles.Label}>{'Label'}</DatePicker.Label>
      <DatePicker.Control class={styles.Control}>
        <DatePicker.Input class={styles.Input} />
        <DatePicker.Trigger class={button.Root}>
          <Calendar />
        </DatePicker.Trigger>
        <DatePicker.ClearTrigger class={button.Root}>{'Clear'}</DatePicker.ClearTrigger>
      </DatePicker.Control>
      <Portal>
        <DatePicker.Positioner>
          <DatePicker.Content class={styles.Content}>
            <DatePicker.View view="day" class={styles.View}>
              <DatePicker.Context>
                component children({ context }) {
                  <DatePicker.ViewControl class={styles.ViewControl}>
                    <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                      <ChevronLeft />
                    </DatePicker.PrevTrigger>
                    <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                      <DatePicker.RangeText />
                    </DatePicker.ViewTrigger>
                    <DatePicker.NextTrigger class={styles.NextTrigger}>
                      <ChevronRight />
                    </DatePicker.NextTrigger>
                  </DatePicker.ViewControl>
                  <DatePicker.Table class={styles.Table}>
                    <DatePicker.TableHead class={styles.TableHead}>
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const weekDay of @context.weekDays; key weekDay.short) {
                          <DatePicker.TableHeader class={styles.TableHeader}>
                            {weekDay.short}
                          </DatePicker.TableHeader>
                        }
                      </DatePicker.TableRow>
                    </DatePicker.TableHead>
                    <DatePicker.TableBody class={styles.TableBody}>
                      for (const week of @context.weeks; key week[0].toString()) {
                        <DatePicker.TableRow class={styles.TableRow}>
                          for (const day of week; key day.toString()) {
                            <DatePicker.TableCell class={styles.TableCell} value={day}>
                              <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                                {day.day}
                              </DatePicker.TableCellTrigger>
                            </DatePicker.TableCell>
                          }
                        </DatePicker.TableRow>
                      }
                    </DatePicker.TableBody>
                  </DatePicker.Table>
                }
              </DatePicker.Context>
            </DatePicker.View>
            <DatePicker.View view="month" class={styles.View}>
              <DatePicker.Context>
                component children({ context }) {
                  <DatePicker.ViewControl class={styles.ViewControl}>
                    <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                      <ChevronLeft />
                    </DatePicker.PrevTrigger>
                    <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                      <DatePicker.RangeText />
                    </DatePicker.ViewTrigger>
                    <DatePicker.NextTrigger class={styles.NextTrigger}>
                      <ChevronRight />
                    </DatePicker.NextTrigger>
                  </DatePicker.ViewControl>
                  <DatePicker.Table class={styles.Table}>
                    <DatePicker.TableBody class={styles.TableBody}>
                      for (const months of @context.getMonthsGrid(
                        { columns: 4, format: 'short' },
                      ); key months[0].value) {
                        <DatePicker.TableRow class={styles.TableRow}>
                          for (const month of months; key month.value) {
                            <DatePicker.TableCell class={styles.TableCell} value={month.value}>
                              <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                                {month.label}
                              </DatePicker.TableCellTrigger>
                            </DatePicker.TableCell>
                          }
                        </DatePicker.TableRow>
                      }
                    </DatePicker.TableBody>
                  </DatePicker.Table>
                }
              </DatePicker.Context>
            </DatePicker.View>
            <DatePicker.View view="year" class={styles.View}>
              <DatePicker.Context>
                component children({ context }) {
                  <DatePicker.ViewControl class={styles.ViewControl}>
                    <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                      <ChevronLeft />
                    </DatePicker.PrevTrigger>
                    <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                      <DatePicker.RangeText />
                    </DatePicker.ViewTrigger>
                    <DatePicker.NextTrigger class={styles.NextTrigger}>
                      <ChevronRight />
                    </DatePicker.NextTrigger>
                  </DatePicker.ViewControl>
                  <DatePicker.Table class={styles.Table}>
                    <DatePicker.TableBody class={styles.TableBody}>
                      for (const years of @context.getYearsGrid(
                        { columns: 4 },
                      ); key years[0].value) {
                        <DatePicker.TableRow class={styles.TableRow}>
                          for (const year of years; key year.value) {
                            <DatePicker.TableCell class={styles.TableCell} value={year.value}>
                              <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                                {year.label}
                              </DatePicker.TableCellTrigger>
                            </DatePicker.TableCell>
                          }
                        </DatePicker.TableRow>
                      }
                    </DatePicker.TableBody>
                  </DatePicker.Table>
                }
              </DatePicker.Context>
            </DatePicker.View>
          </DatePicker.Content>
        </DatePicker.Positioner>
      </Portal>
    </DatePicker.RootProvider>
  </div>
}

```

### Default View

Use the `defaultView` prop to set which view (day, month, or year) the calendar opens to initially.

**Example: default-view**

```ripple
import { DatePicker } from 'ark-ripple/date-picker';
import { Portal } from 'ark-ripple/portal';
import { Calendar, ChevronLeft, ChevronRight } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/date-picker.module.css';

export component DefaultView() {
  <DatePicker.Root class={styles.Root} defaultView="month">
    <DatePicker.Label class={styles.Label}>{'Label'}</DatePicker.Label>
    <DatePicker.Control class={styles.Control}>
      <DatePicker.Input class={styles.Input} />
      <DatePicker.Trigger class={button.Root}>
        <Calendar />
      </DatePicker.Trigger>
      <DatePicker.ClearTrigger class={button.Root}>{'Clear'}</DatePicker.ClearTrigger>
    </DatePicker.Control>
    <Portal>
      <DatePicker.Positioner>
        <DatePicker.Content class={styles.Content}>
          <DatePicker.View view="day" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableHead class={styles.TableHead}>
                    <DatePicker.TableRow class={styles.TableRow}>
                      for (const weekDay of @context.weekDays; key weekDay.short) {
                        <DatePicker.TableHeader class={styles.TableHeader}>
                          {weekDay.short}
                        </DatePicker.TableHeader>
                      }
                    </DatePicker.TableRow>
                  </DatePicker.TableHead>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const week of @context.weeks; key week[0].toString()) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const day of week; key day.toString()) {
                          <DatePicker.TableCell class={styles.TableCell} value={day}>
                            <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                              {day.day}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
          <DatePicker.View view="month" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const months of @context.getMonthsGrid(
                      { columns: 4, format: 'short' },
                    ); key months[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const month of months; key month.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={month.value}>
                            <DatePicker.TableCellTrigger class={styles.MonthTableCellTrigger}>
                              {month.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
          <DatePicker.View view="year" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const years of @context.getYearsGrid({ columns: 4 }); key years[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const year of years; key year.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={year.value}>
                            <DatePicker.TableCellTrigger class={styles.YearTableCellTrigger}>
                              {year.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
        </DatePicker.Content>
      </DatePicker.Positioner>
    </Portal>
  </DatePicker.Root>
}

```

### Month and Year Select

Use `MonthSelect` and `YearSelect` components to create a header with dropdown selects for quick month/year navigation,
alongside the prev/next triggers.

**Example: month-year-select**

```ripple
import { DatePicker } from 'ark-ripple/date-picker';
import { Portal } from 'ark-ripple/portal';
import { Calendar, ChevronLeft, ChevronRight } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/date-picker.module.css';

export component MonthYearSelect() {
  <DatePicker.Root class={styles.Root}>
    <DatePicker.Label class={styles.Label}>{'Label'}</DatePicker.Label>
    <DatePicker.Control class={styles.Control}>
      <DatePicker.Input class={styles.Input} />
      <DatePicker.Trigger class={button.Root}>
        <Calendar />
      </DatePicker.Trigger>
      <DatePicker.ClearTrigger class={button.Root}>{'Clear'}</DatePicker.ClearTrigger>
    </DatePicker.Control>
    <Portal>
      <DatePicker.Positioner>
        <DatePicker.Content class={styles.Content}>
          <DatePicker.View view="day" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <div class={styles.SelectGroup}>
                    <DatePicker.MonthSelect class={styles.MonthSelect} />
                    <DatePicker.YearSelect class={styles.YearSelect} />
                  </div>
                  <div class={styles.SelectGroup}>
                    <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                      <ChevronLeft />
                    </DatePicker.PrevTrigger>
                    <DatePicker.NextTrigger class={styles.NextTrigger}>
                      <ChevronRight />
                    </DatePicker.NextTrigger>
                  </div>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableHead class={styles.TableHead}>
                    <DatePicker.TableRow class={styles.TableRow}>
                      for (const weekDay of @context.weekDays; key weekDay.short) {
                        <DatePicker.TableHeader class={styles.TableHeader}>
                          {weekDay.short}
                        </DatePicker.TableHeader>
                      }
                    </DatePicker.TableRow>
                  </DatePicker.TableHead>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const week of @context.weeks; key week[0].toString()) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const day of week; key day.toString()) {
                          <DatePicker.TableCell class={styles.TableCell} value={day}>
                            <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                              {day.day}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
        </DatePicker.Content>
      </DatePicker.Positioner>
    </Portal>
  </DatePicker.Root>
}

```

### Range

To create a date picker that allows a range selection, you need to:

- Set the `selectionMode` prop to `range`.
- Render multiple inputs with the `index` prop set to `0` and `1`.

**Example: range-selection**

```ripple
import { DatePicker } from 'ark-ripple/date-picker';
import { Portal } from 'ark-ripple/portal';
import { Calendar, ChevronLeft, ChevronRight } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/date-picker.module.css';

export component RangeSelection() {
  <DatePicker.Root class={styles.Root} selectionMode="range">
    <DatePicker.Label class={styles.Label}>{'Label'}</DatePicker.Label>
    <DatePicker.Control class={styles.Control}>
      <DatePicker.Input class={styles.Input} index={0} />
      <DatePicker.Input class={styles.Input} index={1} />
      <DatePicker.Trigger class={button.Root}>
        <Calendar />
      </DatePicker.Trigger>
      <DatePicker.ClearTrigger class={button.Root}>{'Clear'}</DatePicker.ClearTrigger>
    </DatePicker.Control>
    <Portal>
      <DatePicker.Positioner>
        <DatePicker.Content class={styles.Content}>
          <DatePicker.PresetTrigger class={button.Root} value="last7Days">
            {'Last 7 days'}
          </DatePicker.PresetTrigger>
          <DatePicker.View view="day" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableHead class={styles.TableHead}>
                    <DatePicker.TableRow class={styles.TableRow}>
                      for (const weekDay of @context.weekDays; key weekDay.short) {
                        <DatePicker.TableHeader class={styles.TableHeader}>
                          {weekDay.short}
                        </DatePicker.TableHeader>
                      }
                    </DatePicker.TableRow>
                  </DatePicker.TableHead>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const week of @context.weeks; key week[0].toString()) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const day of week; key day.toString()) {
                          <DatePicker.TableCell class={styles.TableCell} value={day}>
                            <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                              {day.day}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
          <DatePicker.View view="month" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const months of @context.getMonthsGrid(
                      { columns: 4, format: 'short' },
                    ); key months[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const month of months; key month.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={month.value}>
                            <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                              {month.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
          <DatePicker.View view="year" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const years of @context.getYearsGrid({ columns: 4 }); key years[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const year of years; key year.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={year.value}>
                            <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                              {year.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
        </DatePicker.Content>
      </DatePicker.Positioner>
    </Portal>
  </DatePicker.Root>
}

```

### Multiple

Use the `selectionMode="multiple"` prop to allow selecting multiple dates. This example also shows how to display
selected dates as removable tags.

**Example: multi-selection**

```ripple
import { DatePicker } from 'ark-ripple/date-picker';
import { Portal } from 'ark-ripple/portal';
import { type DateValue } from '@internationalized/date';
import { Calendar, ChevronLeft, ChevronRight, X } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/date-picker.module.css';

const formatWithDay = (date: DateValue) => new Intl.DateTimeFormat('en', {
  dateStyle: 'medium',
}).format(date.toDate('UTC'));

export component MultiSelection() {
  <DatePicker.Root class={styles.Root} selectionMode="multiple">
    <DatePicker.Label class={styles.Label}>{'Label'}</DatePicker.Label>
    <DatePicker.Control class={styles.Control}>
      <DatePicker.Context>
        component children({ context }) {
          for (const date of @context.value; key date.toString()) {
            <span class={styles.TagItem}>
              <span>{formatWithDay(date)}</span>
              <button
                onClick={() => {
                  @context.setValue(@context.value.filter((v) => v.toString() !== date.toString()));
                }}
              >
                <X />
              </button>
            </span>
          }
        }
      </DatePicker.Context>
      <DatePicker.Input class={styles.Input} />
      <DatePicker.Trigger class={button.Root}>
        <Calendar />
      </DatePicker.Trigger>
      <DatePicker.ClearTrigger class={button.Root}>{'Clear'}</DatePicker.ClearTrigger>
    </DatePicker.Control>
    <Portal>
      <DatePicker.Positioner>
        <DatePicker.Content class={styles.Content}>
          <DatePicker.View view="day" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableHead class={styles.TableHead}>
                    <DatePicker.TableRow class={styles.TableRow}>
                      for (const weekDay of @context.weekDays; key weekDay.short) {
                        <DatePicker.TableHeader class={styles.TableHeader}>
                          {weekDay.short}
                        </DatePicker.TableHeader>
                      }
                    </DatePicker.TableRow>
                  </DatePicker.TableHead>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const week of @context.weeks; key week[0].toString()) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const day of week; key day.toString()) {
                          <DatePicker.TableCell class={styles.TableCell} value={day}>
                            <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                              {day.day}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
          <DatePicker.View view="month" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const months of @context.getMonthsGrid(
                      { columns: 4, format: 'short' },
                    ); key months[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const month of months; key month.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={month.value}>
                            <DatePicker.TableCellTrigger class={styles.MonthTableCellTrigger}>
                              {month.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
          <DatePicker.View view="year" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const years of @context.getYearsGrid({ columns: 4 }); key years[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const year of years; key year.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={year.value}>
                            <DatePicker.TableCellTrigger class={styles.YearTableCellTrigger}>
                              {year.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
        </DatePicker.Content>
      </DatePicker.Positioner>
    </Portal>
  </DatePicker.Root>
}

```

### Max Selected Dates

Use the `maxSelectedDates` prop with `selectionMode="multiple"` to limit the number of dates that can be selected. In
this example, users can select up to 3 dates.

**Example: max-selected-dates**

```ripple
import { DatePicker } from 'ark-ripple/date-picker';
import { ChevronLeft, ChevronRight } from 'lucide-ripple';
import styles from 'styles/date-picker.module.css';

export component MaxSelectedDates() {
  <DatePicker.Root class={styles.Root} selectionMode="multiple" maxSelectedDates={3} inline>
    <DatePicker.Label class={styles.Label}>{'Label'}</DatePicker.Label>
    <div class={styles.Content}>
      <DatePicker.View view="day" class={styles.View}>
        <DatePicker.Context>
          component children({ context }) {
            <DatePicker.ViewControl class={styles.ViewControl}>
              <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                <ChevronLeft />
              </DatePicker.PrevTrigger>
              <DatePicker.RangeText class={styles.RangeText} />
              <DatePicker.NextTrigger class={styles.NextTrigger}>
                <ChevronRight />
              </DatePicker.NextTrigger>
            </DatePicker.ViewControl>
            <DatePicker.Table class={styles.Table}>
              <DatePicker.TableHead class={styles.TableHead}>
                <DatePicker.TableRow class={styles.TableRow}>
                  for (const weekDay of @context.weekDays; key weekDay.short) {
                    <DatePicker.TableHeader class={styles.TableHeader}>
                      {weekDay.short}
                    </DatePicker.TableHeader>
                  }
                </DatePicker.TableRow>
              </DatePicker.TableHead>
              <DatePicker.TableBody class={styles.TableBody}>
                for (const week of @context.weeks; key week[0].toString()) {
                  <DatePicker.TableRow class={styles.TableRow}>
                    for (const day of week; key day.toString()) {
                      <DatePicker.TableCell class={styles.TableCell} value={day}>
                        <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                          {day.day}
                        </DatePicker.TableCellTrigger>
                      </DatePicker.TableCell>
                    }
                  </DatePicker.TableRow>
                }
              </DatePicker.TableBody>
            </DatePicker.Table>
          }
        </DatePicker.Context>
      </DatePicker.View>
    </div>
  </DatePicker.Root>
}

```

### Multiple Months

To create a date picker that displays multiple months side by side:

- Set the `numOfMonths` prop to the number of months you want to display.
- Use the `datePicker.getOffset({ months: 1 })` to get data for the next month.

**Example: multiple-months**

```ripple
import { DatePicker } from 'ark-ripple/date-picker';
import { Calendar, ChevronLeft, ChevronRight } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/date-picker.module.css';

export component MultipleMonths() {
  <DatePicker.Root class={styles.Root} numOfMonths={2}>
    <DatePicker.Label class={styles.Label}>{'Label'}</DatePicker.Label>
    <DatePicker.Control class={styles.Control}>
      <DatePicker.Input class={styles.Input} index={0} />
      <DatePicker.Trigger class={button.Root}>
        <Calendar />
      </DatePicker.Trigger>
      <DatePicker.ClearTrigger class={button.Root}>{'Clear'}</DatePicker.ClearTrigger>
    </DatePicker.Control>
    <DatePicker.Positioner>
      <DatePicker.Content class={styles.Content}>
        <DatePicker.ViewControl class={styles.ViewControl}>
          <DatePicker.PrevTrigger class={styles.PrevTrigger}>
            <ChevronLeft />
          </DatePicker.PrevTrigger>
          <DatePicker.RangeText class={styles.RangeText} />
          <DatePicker.NextTrigger class={styles.NextTrigger}>
            <ChevronRight />
          </DatePicker.NextTrigger>
        </DatePicker.ViewControl>
        <div class={styles.MultipleMonths}>
          <DatePicker.View view="day" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableHead class={styles.TableHead}>
                    <DatePicker.TableRow class={styles.TableRow}>
                      for (const weekDay of @context.weekDays; key weekDay.short) {
                        <DatePicker.TableHeader class={styles.TableHeader}>
                          {weekDay.short}
                        </DatePicker.TableHeader>
                      }
                    </DatePicker.TableRow>
                  </DatePicker.TableHead>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const week of @context.weeks; key week[0].toString()) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const day of week; key day.toString()) {
                          <DatePicker.TableCell class={styles.TableCell} value={day}>
                            <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                              {day.day}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
          <DatePicker.View view="day" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                const offset = @context.getOffset({ months: 1 });
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableHead class={styles.TableHead}>
                    <DatePicker.TableRow class={styles.TableRow}>
                      for (const weekDay of @context.weekDays; key weekDay.short) {
                        <DatePicker.TableHeader class={styles.TableHeader}>
                          {weekDay.short}
                        </DatePicker.TableHeader>
                      }
                    </DatePicker.TableRow>
                  </DatePicker.TableHead>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const week of offset.weeks; key week[0].toString()) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const day of week; key day.toString()) {
                          <DatePicker.TableCell
                            class={styles.TableCell}
                            value={day}
                            visibleRange={offset.visibleRange}
                          >
                            <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                              {day.day}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
        </div>
      </DatePicker.Content>
    </DatePicker.Positioner>
  </DatePicker.Root>
}

```

### Presets

Use the `DatePicker.PresetTrigger` component to add quick-select preset options like "Last 7 days" or "This month".

**Example: presets**

```ripple
import { DatePicker } from 'ark-ripple/date-picker';
import { Portal } from 'ark-ripple/portal';
import { Calendar, ChevronLeft, ChevronRight } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/date-picker.module.css';

export component Presets() {
  <DatePicker.Root class={styles.Root} selectionMode="range">
    <DatePicker.Label class={styles.Label}>{'Label'}</DatePicker.Label>
    <DatePicker.Control class={styles.Control}>
      <DatePicker.Input class={styles.Input} index={0} />
      <DatePicker.Input class={styles.Input} index={1} />
      <DatePicker.Trigger class={button.Root}>
        <Calendar />
      </DatePicker.Trigger>
      <DatePicker.ClearTrigger class={button.Root}>{'Clear'}</DatePicker.ClearTrigger>
    </DatePicker.Control>
    <Portal>
      <DatePicker.Positioner>
        <DatePicker.Content class={styles.Content}>
          <div class={styles.PresetGroup}>
            <DatePicker.PresetTrigger class={button.Root} value="last7Days">
              {'Last 7 days'}
            </DatePicker.PresetTrigger>
            <DatePicker.PresetTrigger class={button.Root} value="last14Days">
              {'Last 14 days'}
            </DatePicker.PresetTrigger>
            <DatePicker.PresetTrigger class={button.Root} value="last30Days">
              {'Last 30 days'}
            </DatePicker.PresetTrigger>
            <DatePicker.PresetTrigger class={button.Root} value="last90Days">
              {'Last 90 days'}
            </DatePicker.PresetTrigger>
          </div>
          <DatePicker.View view="day" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableHead class={styles.TableHead}>
                    <DatePicker.TableRow class={styles.TableRow}>
                      for (const weekDay of @context.weekDays; key weekDay.short) {
                        <DatePicker.TableHeader class={styles.TableHeader}>
                          {weekDay.short}
                        </DatePicker.TableHeader>
                      }
                    </DatePicker.TableRow>
                  </DatePicker.TableHead>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const week of @context.weeks; key week[0].toString()) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const day of week; key day.toString()) {
                          <DatePicker.TableCell class={styles.TableCell} value={day}>
                            <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                              {day.day}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
          <DatePicker.View view="month" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const months of @context.getMonthsGrid(
                      { columns: 4, format: 'short' },
                    ); key months[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const month of months; key month.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={month.value}>
                            <DatePicker.TableCellTrigger class={styles.MonthTableCellTrigger}>
                              {month.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
          <DatePicker.View view="year" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const years of @context.getYearsGrid({ columns: 4 }); key years[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const year of years; key year.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={year.value}>
                            <DatePicker.TableCellTrigger class={styles.YearTableCellTrigger}>
                              {year.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
        </DatePicker.Content>
      </DatePicker.Positioner>
    </Portal>
  </DatePicker.Root>
}

```

### Min and Max

Use the `min` and `max` props with `parseDate` to restrict the selectable date range. Dates outside this range will be
disabled.

**Example: min-max**

```ripple
import { DatePicker, parseDate } from 'ark-ripple/date-picker';
import { Portal } from 'ark-ripple/portal';
import { Calendar, ChevronLeft, ChevronRight } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/date-picker.module.css';

export component MinMax() {
  <DatePicker.Root class={styles.Root} min={parseDate('2024-01-01')} max={parseDate('2024-12-31')}>
    <DatePicker.Label class={styles.Label}>{'Label'}</DatePicker.Label>
    <DatePicker.Control class={styles.Control}>
      <DatePicker.Input class={styles.Input} />
      <DatePicker.Trigger class={button.Root}>
        <Calendar />
      </DatePicker.Trigger>
      <DatePicker.ClearTrigger class={button.Root}>{'Clear'}</DatePicker.ClearTrigger>
    </DatePicker.Control>
    <Portal>
      <DatePicker.Positioner>
        <DatePicker.Content class={styles.Content}>
          <DatePicker.View view="day" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableHead class={styles.TableHead}>
                    <DatePicker.TableRow class={styles.TableRow}>
                      for (const weekDay of @context.weekDays; key weekDay.short) {
                        <DatePicker.TableHeader class={styles.TableHeader}>
                          {weekDay.short}
                        </DatePicker.TableHeader>
                      }
                    </DatePicker.TableRow>
                  </DatePicker.TableHead>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const week of @context.weeks; key week[0].toString()) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const day of week; key day.toString()) {
                          <DatePicker.TableCell class={styles.TableCell} value={day}>
                            <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                              {day.day}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
          <DatePicker.View view="month" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const months of @context.getMonthsGrid(
                      { columns: 4, format: 'short' },
                    ); key months[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const month of months; key month.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={month.value}>
                            <DatePicker.TableCellTrigger class={styles.MonthTableCellTrigger}>
                              {month.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
          <DatePicker.View view="year" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const years of @context.getYearsGrid({ columns: 4 }); key years[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const year of years; key year.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={year.value}>
                            <DatePicker.TableCellTrigger class={styles.YearTableCellTrigger}>
                              {year.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
        </DatePicker.Content>
      </DatePicker.Positioner>
    </Portal>
  </DatePicker.Root>
}

```

### Unavailable

Use the `isDateUnavailable` prop to mark specific dates as unavailable. This example disables weekends.

**Example: unavailable**

```ripple
import { DatePicker } from 'ark-ripple/date-picker';
import { Portal } from 'ark-ripple/portal';
import { isWeekend } from '@internationalized/date';
import { Calendar, ChevronLeft, ChevronRight } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/date-picker.module.css';

export component Unavailable() {
  <DatePicker.Root
    class={styles.Root}
    isDateUnavailable={(date, locale) => isWeekend(date, locale)}
  >
    <DatePicker.Label class={styles.Label}>{'Label'}</DatePicker.Label>
    <DatePicker.Control class={styles.Control}>
      <DatePicker.Input class={styles.Input} />
      <DatePicker.Trigger class={button.Root}>
        <Calendar />
      </DatePicker.Trigger>
      <DatePicker.ClearTrigger class={button.Root}>{'Clear'}</DatePicker.ClearTrigger>
    </DatePicker.Control>
    <Portal>
      <DatePicker.Positioner>
        <DatePicker.Content class={styles.Content}>
          <DatePicker.View view="day" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableHead class={styles.TableHead}>
                    <DatePicker.TableRow class={styles.TableRow}>
                      for (const weekDay of @context.weekDays; key weekDay.short) {
                        <DatePicker.TableHeader class={styles.TableHeader}>
                          {weekDay.short}
                        </DatePicker.TableHeader>
                      }
                    </DatePicker.TableRow>
                  </DatePicker.TableHead>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const week of @context.weeks; key week[0].toString()) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const day of week; key day.toString()) {
                          <DatePicker.TableCell class={styles.TableCell} value={day}>
                            <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                              {day.day}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
          <DatePicker.View view="month" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const months of @context.getMonthsGrid(
                      { columns: 4, format: 'short' },
                    ); key months[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const month of months; key month.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={month.value}>
                            <DatePicker.TableCellTrigger class={styles.MonthTableCellTrigger}>
                              {month.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
          <DatePicker.View view="year" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const years of @context.getYearsGrid({ columns: 4 }); key years[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const year of years; key year.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={year.value}>
                            <DatePicker.TableCellTrigger class={styles.YearTableCellTrigger}>
                              {year.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
        </DatePicker.Content>
      </DatePicker.Positioner>
    </Portal>
  </DatePicker.Root>
}

```

### Locale

Use the `locale` prop to set the language and formatting, and `startOfWeek` to set the first day of the week (0 =
Sunday, 1 = Monday, etc.).

**Example: locale**

```ripple
import { DatePicker } from 'ark-ripple/date-picker';
import { Portal } from 'ark-ripple/portal';
import { Calendar, ChevronLeft, ChevronRight } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/date-picker.module.css';

export component Locale() {
  <DatePicker.Root class={styles.Root} locale="de-DE">
    <DatePicker.Label class={styles.Label}>{'Beschriftung'}</DatePicker.Label>
    <DatePicker.Control class={styles.Control}>
      <DatePicker.Input class={styles.Input} />
      <DatePicker.Trigger class={button.Root}>
        <Calendar />
      </DatePicker.Trigger>
      <DatePicker.ClearTrigger class={button.Root}>{'Löschen'}</DatePicker.ClearTrigger>
    </DatePicker.Control>
    <Portal>
      <DatePicker.Positioner>
        <DatePicker.Content class={styles.Content}>
          <DatePicker.View view="day" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableHead class={styles.TableHead}>
                    <DatePicker.TableRow class={styles.TableRow}>
                      for (const weekDay of @context.weekDays; key weekDay.short) {
                        <DatePicker.TableHeader class={styles.TableHeader}>
                          {weekDay.short}
                        </DatePicker.TableHeader>
                      }
                    </DatePicker.TableRow>
                  </DatePicker.TableHead>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const week of @context.weeks; key week[0].toString()) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const day of week; key day.toString()) {
                          <DatePicker.TableCell class={styles.TableCell} value={day}>
                            <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                              {day.day}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
          <DatePicker.View view="month" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const months of @context.getMonthsGrid(
                      { columns: 4, format: 'short' },
                    ); key months[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const month of months; key month.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={month.value}>
                            <DatePicker.TableCellTrigger class={styles.MonthTableCellTrigger}>
                              {month.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
          <DatePicker.View view="year" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const years of @context.getYearsGrid({ columns: 4 }); key years[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const year of years; key year.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={year.value}>
                            <DatePicker.TableCellTrigger class={styles.YearTableCellTrigger}>
                              {year.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
        </DatePicker.Content>
      </DatePicker.Positioner>
    </Portal>
  </DatePicker.Root>
}

```

### Month Picker

Create a month-only picker by setting `defaultView="month"` and `minView="month"`. Use custom `format` and `parse`
functions to handle month/year input format.

**Example: month-picker**

```ripple
import { DatePicker } from 'ark-ripple/date-picker';
import { Portal } from 'ark-ripple/portal';
import { CalendarDate, type DateValue } from '@internationalized/date';
import { Calendar, ChevronLeft, ChevronRight } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/date-picker.module.css';

const format = (date: DateValue) => {
  const month = String(date.month).padStart(2, '0');
  const year = String(date.year);
  return `${month}/${year}`;
};

const parse = (value: string) => {
  const fullRegex = /^(\d{1,2})\/(\d{4})$/;
  const fullMatch = value.match(fullRegex);
  if (fullMatch) {
    const [, month, year] = fullMatch.map(Number);
    return new CalendarDate(year, month, 1);
  }
  return undefined;
};

export component MonthPicker() {
  <DatePicker.Root
    class={styles.Root}
    {format}
    {parse}
    defaultView="month"
    minView="month"
    placeholder="mm/yyyy"
  >
    <DatePicker.Label class={styles.Label}>{'Label'}</DatePicker.Label>
    <DatePicker.Control class={styles.Control}>
      <DatePicker.Input class={styles.Input} />
      <DatePicker.Trigger class={button.Root}>
        <Calendar />
      </DatePicker.Trigger>
      <DatePicker.ClearTrigger class={button.Root}>{'Clear'}</DatePicker.ClearTrigger>
    </DatePicker.Control>
    <Portal>
      <DatePicker.Positioner>
        <DatePicker.Content class={styles.Content}>
          <DatePicker.View view="month" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const months of @context.getMonthsGrid(
                      { columns: 4, format: 'short' },
                    ); key months[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const month of months; key month.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={month.value}>
                            <DatePicker.TableCellTrigger class={styles.MonthTableCellTrigger}>
                              {month.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
          <DatePicker.View view="year" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const years of @context.getYearsGrid({ columns: 4 }); key years[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const year of years; key year.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={year.value}>
                            <DatePicker.TableCellTrigger class={styles.YearTableCellTrigger}>
                              {year.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
        </DatePicker.Content>
      </DatePicker.Positioner>
    </Portal>
  </DatePicker.Root>
}

```

### Year Picker

Create a year-only picker by setting `defaultView="year"` and `minView="year"`. Use custom `format` and `parse`
functions to handle year-only input format.

**Example: year-picker**

```ripple
import { DatePicker, parseDate } from 'ark-ripple/date-picker';
import { Portal } from 'ark-ripple/portal';
import { CalendarDate, type DateValue } from '@internationalized/date';
import { Calendar, ChevronLeft, ChevronRight } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/date-picker.module.css';

const format = (date: DateValue) => String(date.year);

const parse = (value: string) => {
  const fullRegex = /^(\d{4})$/;
  const fullMatch = value.match(fullRegex);
  if (fullMatch) {
    const [, year] = fullMatch.map(Number);
    return new CalendarDate(year, 1, 1);
  }
  return undefined;
};

export component YearPicker() {
  <DatePicker.Root
    class={styles.Root}
    defaultView="year"
    minView="year"
    {format}
    {parse}
    placeholder="yyyy"
  >
    <DatePicker.Label class={styles.Label}>{'Label'}</DatePicker.Label>
    <DatePicker.Control class={styles.Control}>
      <DatePicker.Input class={styles.Input} />
      <DatePicker.Trigger class={button.Root}>
        <Calendar />
      </DatePicker.Trigger>
      <DatePicker.ClearTrigger class={button.Root}>{'Clear'}</DatePicker.ClearTrigger>
    </DatePicker.Control>
    <Portal>
      <DatePicker.Positioner>
        <DatePicker.Content class={styles.Content}>
          <DatePicker.View view="year" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const years of @context.getYearsGrid({ columns: 4 }); key years[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const year of years; key year.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={year.value}>
                            <DatePicker.TableCellTrigger class={styles.YearTableCellTrigger}>
                              {year.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
        </DatePicker.Content>
      </DatePicker.Positioner>
    </Portal>
  </DatePicker.Root>
}

```

### Inline

Use the `inline` prop to display the date picker directly on the page, without a popup.

> When using the `inline` prop, omit the `Portal`, `Positioner`, and `Content` components to render the calendar inline
> within your layout.

**Example: inline**

```ripple
import { DatePicker } from 'ark-ripple/date-picker';
import { ChevronLeft, ChevronRight } from 'lucide-ripple';
import styles from 'styles/date-picker.module.css';

export component Inline() {
  <DatePicker.Root class={styles.Root} inline>
    <DatePicker.Label class={styles.Label}>{'Label'}</DatePicker.Label>
    <div class={styles.Content}>
      <DatePicker.View view="day" class={styles.View}>
        <DatePicker.Context>
          component children({ context }) {
            <DatePicker.ViewControl class={styles.ViewControl}>
              <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                <ChevronLeft />
              </DatePicker.PrevTrigger>
              <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                <DatePicker.RangeText />
              </DatePicker.ViewTrigger>
              <DatePicker.NextTrigger class={styles.NextTrigger}>
                <ChevronRight />
              </DatePicker.NextTrigger>
            </DatePicker.ViewControl>
            <DatePicker.Table class={styles.Table}>
              <DatePicker.TableHead class={styles.TableHead}>
                <DatePicker.TableRow class={styles.TableRow}>
                  for (const weekDay of @context.weekDays; key weekDay.short) {
                    <DatePicker.TableHeader class={styles.TableHeader}>
                      {weekDay.short}
                    </DatePicker.TableHeader>
                  }
                </DatePicker.TableRow>
              </DatePicker.TableHead>
              <DatePicker.TableBody class={styles.TableBody}>
                for (const week of @context.weeks; key week[0].toString()) {
                  <DatePicker.TableRow class={styles.TableRow}>
                    for (const day of week; key day.toString()) {
                      <DatePicker.TableCell class={styles.TableCell} value={day}>
                        <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                          {day.day}
                        </DatePicker.TableCellTrigger>
                      </DatePicker.TableCell>
                    }
                  </DatePicker.TableRow>
                }
              </DatePicker.TableBody>
            </DatePicker.Table>
          }
        </DatePicker.Context>
      </DatePicker.View>
      <DatePicker.View view="month" class={styles.View}>
        <DatePicker.Context>
          component children({ context }) {
            <DatePicker.ViewControl class={styles.ViewControl}>
              <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                <ChevronLeft />
              </DatePicker.PrevTrigger>
              <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                <DatePicker.RangeText />
              </DatePicker.ViewTrigger>
              <DatePicker.NextTrigger class={styles.NextTrigger}>
                <ChevronRight />
              </DatePicker.NextTrigger>
            </DatePicker.ViewControl>
            <DatePicker.Table class={styles.Table}>
              <DatePicker.TableBody class={styles.TableBody}>
                for (const months of @context.getMonthsGrid(
                  { columns: 4, format: 'short' },
                ); key months[0].value) {
                  <DatePicker.TableRow class={styles.TableRow}>
                    for (const month of months; key month.value) {
                      <DatePicker.TableCell class={styles.TableCell} value={month.value}>
                        <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                          {month.label}
                        </DatePicker.TableCellTrigger>
                      </DatePicker.TableCell>
                    }
                  </DatePicker.TableRow>
                }
              </DatePicker.TableBody>
            </DatePicker.Table>
          }
        </DatePicker.Context>
      </DatePicker.View>
      <DatePicker.View view="year" class={styles.View}>
        <DatePicker.Context>
          component children({ context }) {
            <DatePicker.ViewControl class={styles.ViewControl}>
              <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                <ChevronLeft />
              </DatePicker.PrevTrigger>
              <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                <DatePicker.RangeText />
              </DatePicker.ViewTrigger>
              <DatePicker.NextTrigger class={styles.NextTrigger}>
                <ChevronRight />
              </DatePicker.NextTrigger>
            </DatePicker.ViewControl>
            <DatePicker.Table class={styles.Table}>
              <DatePicker.TableBody class={styles.TableBody}>
                for (const years of @context.getYearsGrid({ columns: 4 }); key years[0].value) {
                  <DatePicker.TableRow class={styles.TableRow}>
                    for (const year of years; key year.value) {
                      <DatePicker.TableCell class={styles.TableCell} value={year.value}>
                        <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                          {year.label}
                        </DatePicker.TableCellTrigger>
                      </DatePicker.TableCell>
                    }
                  </DatePicker.TableRow>
                }
              </DatePicker.TableBody>
            </DatePicker.Table>
          }
        </DatePicker.Context>
      </DatePicker.View>
    </div>
  </DatePicker.Root>
}

```

### Custom Parsing

Use the `parse` prop to implement custom date parsing logic. This allows users to enter dates in flexible formats like
"25/12" or "25/12/24" which are automatically converted to valid dates.

**Example: format-parse**

```ripple
import { DatePicker, parseDate } from 'ark-ripple/date-picker';
import { Portal } from 'ark-ripple/portal';
import { type DateValue } from '@internationalized/date';
import { Calendar, ChevronLeft, ChevronRight } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/date-picker.module.css';

const format = (date: DateValue) => {
  const day = String(date.day).padStart(2, '0');
  const month = String(date.month).padStart(2, '0');
  const year = String(date.year);
  return `${day}/${month}/${year}`;
};

const parse = (value: string) => {
  const fullRegex = /^(\d{1,2})\/(\d{1,2})\/(\d{4})$/;
  const fullMatch = value.match(fullRegex);
  if (fullMatch) {
    const [, day, month, year] = fullMatch.map(Number);
    return parseDate(`${year}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')}`);
  }
  return undefined;
};

export component FormatParse() {
  <DatePicker.Root class={styles.Root} {format} {parse} placeholder="dd/mm/yyyy">
    <DatePicker.Label class={styles.Label}>{'Label'}</DatePicker.Label>
    <DatePicker.Control class={styles.Control}>
      <DatePicker.Input class={styles.Input} />
      <DatePicker.Trigger class={button.Root}>
        <Calendar />
      </DatePicker.Trigger>
      <DatePicker.ClearTrigger class={button.Root}>{'Clear'}</DatePicker.ClearTrigger>
    </DatePicker.Control>
    <Portal>
      <DatePicker.Positioner>
        <DatePicker.Content class={styles.Content}>
          <DatePicker.View view="day" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableHead class={styles.TableHead}>
                    <DatePicker.TableRow class={styles.TableRow}>
                      for (const weekDay of @context.weekDays; key weekDay.short) {
                        <DatePicker.TableHeader class={styles.TableHeader}>
                          {weekDay.short}
                        </DatePicker.TableHeader>
                      }
                    </DatePicker.TableRow>
                  </DatePicker.TableHead>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const week of @context.weeks; key week[0].toString()) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const day of week; key day.toString()) {
                          <DatePicker.TableCell class={styles.TableCell} value={day}>
                            <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                              {day.day}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
          <DatePicker.View view="month" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const months of @context.getMonthsGrid(
                      { columns: 4, format: 'short' },
                    ); key months[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const month of months; key month.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={month.value}>
                            <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                              {month.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
          <DatePicker.View view="year" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const years of @context.getYearsGrid({ columns: 4 }); key years[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const year of years; key year.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={year.value}>
                            <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                              {year.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
        </DatePicker.Content>
      </DatePicker.Positioner>
    </Portal>
  </DatePicker.Root>
}

```

### Month Picker Range

Create a month range picker by combining `selectionMode="range"` with `defaultView="month"` and `minView="month"`. This
is useful for selecting billing periods or date ranges by month.

**Example: month-picker-range**

```ripple
import { DatePicker } from 'ark-ripple/date-picker';
import { Portal } from 'ark-ripple/portal';
import { CalendarDate, type DateValue } from '@internationalized/date';
import { Calendar, ChevronLeft, ChevronRight } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/date-picker.module.css';

const format = (date: DateValue) => {
  const month = String(date.month).padStart(2, '0');
  const year = String(date.year);
  return `${month}/${year}`;
};

const parse = (value: string) => {
  const fullRegex = /^(\d{1,2})\/(\d{4})$/;
  const fullMatch = value.match(fullRegex);
  if (fullMatch) {
    const [, month, year] = fullMatch.map(Number);
    return new CalendarDate(year, month, 1);
  }
  return undefined;
};

export component MonthPickerRange() {
  <DatePicker.Root
    class={styles.Root}
    selectionMode="range"
    defaultView="month"
    minView="month"
    {format}
    {parse}
    placeholder="mm/yyyy"
  >
    <DatePicker.Label class={styles.Label}>{'Label'}</DatePicker.Label>
    <DatePicker.Control class={styles.Control}>
      <DatePicker.Input class={styles.Input} index={0} />
      <DatePicker.Input class={styles.Input} index={1} />
      <DatePicker.Trigger class={button.Root}>
        <Calendar />
      </DatePicker.Trigger>
      <DatePicker.ClearTrigger class={button.Root}>{'Clear'}</DatePicker.ClearTrigger>
    </DatePicker.Control>
    <Portal>
      <DatePicker.Positioner>
        <DatePicker.Content class={styles.Content}>
          <DatePicker.View view="month" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const months of @context.getMonthsGrid(
                      { columns: 4, format: 'short' },
                    ); key months[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const month of months; key month.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={month.value}>
                            <DatePicker.TableCellTrigger class={styles.MonthTableCellTrigger}>
                              {month.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
          <DatePicker.View view="year" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const years of @context.getYearsGrid({ columns: 4 }); key years[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const year of years; key year.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={year.value}>
                            <DatePicker.TableCellTrigger class={styles.YearTableCellTrigger}>
                              {year.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
        </DatePicker.Content>
      </DatePicker.Positioner>
    </Portal>
  </DatePicker.Root>
}

```

### Year Range

Create a year range picker by combining `selectionMode="range"` with `defaultView="year"` and `minView="year"`. This is
useful for selecting multi-year periods.

**Example: year-picker-range**

```ripple
import { DatePicker } from 'ark-ripple/date-picker';
import { Portal } from 'ark-ripple/portal';
import { CalendarDate, type DateValue } from '@internationalized/date';
import { Calendar, ChevronLeft, ChevronRight } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/date-picker.module.css';

const format = (date: DateValue) => String(date.year);

const parse = (value: string) => {
  const fullRegex = /^(\d{4})$/;
  const fullMatch = value.match(fullRegex);
  if (fullMatch) {
    const [, year] = fullMatch.map(Number);
    return new CalendarDate(year, 1, 1);
  }
  return undefined;
};

export component YearPickerRange() {
  <DatePicker.Root
    class={styles.Root}
    selectionMode="range"
    defaultView="year"
    minView="year"
    {format}
    {parse}
    placeholder="yyyy"
  >
    <DatePicker.Label class={styles.Label}>{'Label'}</DatePicker.Label>
    <DatePicker.Control class={styles.Control}>
      <DatePicker.Input class={styles.Input} index={0} />
      <DatePicker.Input class={styles.Input} index={1} />
      <DatePicker.Trigger class={button.Root}>
        <Calendar />
      </DatePicker.Trigger>
      <DatePicker.ClearTrigger class={button.Root}>{'Clear'}</DatePicker.ClearTrigger>
    </DatePicker.Control>
    <Portal>
      <DatePicker.Positioner>
        <DatePicker.Content class={styles.Content}>
          <DatePicker.View view="year" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <span class={styles.ViewTrigger}>
                    {@context.getDecade().start}
                    {' - '}
                    {@context.getDecade().end}
                  </span>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const years of @context.getYearsGrid({ columns: 4 }); key years[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const year of years; key year.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={year.value}>
                            <DatePicker.TableCellTrigger class={styles.YearTableCellTrigger}>
                              {year.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
        </DatePicker.Content>
      </DatePicker.Positioner>
    </Portal>
  </DatePicker.Root>
}

```

### Select Today

Use the `selectToday` method from the date picker context to add a "Today" button that quickly selects the current date.

**Example: select-today**

```ripple
import { DatePicker } from 'ark-ripple/date-picker';
import { Portal } from 'ark-ripple/portal';
import { Calendar, ChevronLeft, ChevronRight } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/date-picker.module.css';

export component SelectToday() {
  <DatePicker.Root class={styles.Root}>
    <DatePicker.Label class={styles.Label}>{'Label'}</DatePicker.Label>
    <DatePicker.Control class={styles.Control}>
      <DatePicker.Input class={styles.Input} />
      <DatePicker.Trigger class={button.Root}>
        <Calendar />
      </DatePicker.Trigger>
      <DatePicker.ClearTrigger class={button.Root}>{'Clear'}</DatePicker.ClearTrigger>
    </DatePicker.Control>
    <Portal>
      <DatePicker.Positioner>
        <DatePicker.Content class={styles.Content}>
          <DatePicker.View view="day" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableHead class={styles.TableHead}>
                    <DatePicker.TableRow class={styles.TableRow}>
                      for (const weekDay of @context.weekDays; key weekDay.short) {
                        <DatePicker.TableHeader class={styles.TableHeader}>
                          {weekDay.short}
                        </DatePicker.TableHeader>
                      }
                    </DatePicker.TableRow>
                  </DatePicker.TableHead>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const week of @context.weeks; key week[0].toString()) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const day of week; key day.toString()) {
                          <DatePicker.TableCell class={styles.TableCell} value={day}>
                            <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                              {day.day}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
                <button class={button.Root} type="button" onClick={() => @context.selectToday()}>
                  {'Today'}
                </button>
              }
            </DatePicker.Context>
          </DatePicker.View>
          <DatePicker.View view="month" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const months of @context.getMonthsGrid(
                      { columns: 4, format: 'short' },
                    ); key months[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const month of months; key month.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={month.value}>
                            <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                              {month.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
          <DatePicker.View view="year" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const years of @context.getYearsGrid({ columns: 4 }); key years[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const year of years; key year.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={year.value}>
                            <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                              {year.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
        </DatePicker.Content>
      </DatePicker.Positioner>
    </Portal>
  </DatePicker.Root>
}

```

### Fixed Weeks

Use the `fixedWeeks` prop to always display 6 weeks in the calendar, preventing layout shifts when navigating between
months.

**Example: fixed-weeks**

```ripple
import { DatePicker } from 'ark-ripple/date-picker';
import { Portal } from 'ark-ripple/portal';
import { Calendar, ChevronLeft, ChevronRight } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/date-picker.module.css';

export component FixedWeeks() {
  <DatePicker.Root class={styles.Root} fixedWeeks>
    <DatePicker.Label class={styles.Label}>{'Label'}</DatePicker.Label>
    <DatePicker.Control class={styles.Control}>
      <DatePicker.Input class={styles.Input} />
      <DatePicker.Trigger class={button.Root}>
        <Calendar />
      </DatePicker.Trigger>
      <DatePicker.ClearTrigger class={button.Root}>{'Clear'}</DatePicker.ClearTrigger>
    </DatePicker.Control>
    <Portal>
      <DatePicker.Positioner>
        <DatePicker.Content class={styles.Content}>
          <DatePicker.View view="day" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableHead class={styles.TableHead}>
                    <DatePicker.TableRow class={styles.TableRow}>
                      for (const weekDay of @context.weekDays; key weekDay.short) {
                        <DatePicker.TableHeader class={styles.TableHeader}>
                          {weekDay.short}
                        </DatePicker.TableHeader>
                      }
                    </DatePicker.TableRow>
                  </DatePicker.TableHead>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const week of @context.weeks; key week[0].toString()) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const day of week; key day.toString()) {
                          <DatePicker.TableCell class={styles.TableCell} value={day}>
                            <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                              {day.day}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
          <DatePicker.View view="month" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const months of @context.getMonthsGrid(
                      { columns: 4, format: 'short' },
                    ); key months[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const month of months; key month.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={month.value}>
                            <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                              {month.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
          <DatePicker.View view="year" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const years of @context.getYearsGrid({ columns: 4 }); key years[0].value) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const year of years; key year.value) {
                          <DatePicker.TableCell class={styles.TableCell} value={year.value}>
                            <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                              {year.label}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
              }
            </DatePicker.Context>
          </DatePicker.View>
        </DatePicker.Content>
      </DatePicker.Positioner>
    </Portal>
  </DatePicker.Root>
}

```

### Form

Use the `name` prop to integrate the date picker with native HTML forms. The selected date value will be submitted as
form data. This example also uses `isDateUnavailable` to disable weekends.

**Example: form**

```ripple
import { DatePicker } from 'ark-ripple/date-picker';
import { Portal } from 'ark-ripple/portal';
import { isWeekend } from '@internationalized/date';
import { Calendar, ChevronLeft, ChevronRight } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/date-picker.module.css';

export component Form() {
  <form
    onSubmit={(e) => {
      e.preventDefault();
    }}
  >
    <DatePicker.Root
      class={styles.Root}
      name="date"
      isDateUnavailable={(date, locale) => isWeekend(date, locale)}
    >
      <DatePicker.Label class={styles.Label}>{'Label'}</DatePicker.Label>
      <DatePicker.Control class={styles.Control}>
        <DatePicker.Input class={styles.Input} />
        <DatePicker.Trigger class={button.Root}>
          <Calendar />
        </DatePicker.Trigger>
        <DatePicker.ClearTrigger class={button.Root}>{'Clear'}</DatePicker.ClearTrigger>
      </DatePicker.Control>
      <Portal>
        <DatePicker.Positioner>
          <DatePicker.Content class={styles.Content}>
            <DatePicker.View view="day" class={styles.View}>
              <DatePicker.Context>
                component children({ context }) {
                  <DatePicker.ViewControl class={styles.ViewControl}>
                    <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                      <ChevronLeft />
                    </DatePicker.PrevTrigger>
                    <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                      <DatePicker.RangeText />
                    </DatePicker.ViewTrigger>
                    <DatePicker.NextTrigger class={styles.NextTrigger}>
                      <ChevronRight />
                    </DatePicker.NextTrigger>
                  </DatePicker.ViewControl>
                  <DatePicker.Table class={styles.Table}>
                    <DatePicker.TableHead class={styles.TableHead}>
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const weekDay of @context.weekDays; key weekDay.short) {
                          <DatePicker.TableHeader class={styles.TableHeader}>
                            {weekDay.short}
                          </DatePicker.TableHeader>
                        }
                      </DatePicker.TableRow>
                    </DatePicker.TableHead>
                    <DatePicker.TableBody class={styles.TableBody}>
                      for (const week of @context.weeks; key week[0].toString()) {
                        <DatePicker.TableRow class={styles.TableRow}>
                          for (const day of week; key day.toString()) {
                            <DatePicker.TableCell class={styles.TableCell} value={day}>
                              <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                                {day.day}
                              </DatePicker.TableCellTrigger>
                            </DatePicker.TableCell>
                          }
                        </DatePicker.TableRow>
                      }
                    </DatePicker.TableBody>
                  </DatePicker.Table>
                }
              </DatePicker.Context>
            </DatePicker.View>
            <DatePicker.View view="month" class={styles.View}>
              <DatePicker.Context>
                component children({ context }) {
                  <DatePicker.ViewControl class={styles.ViewControl}>
                    <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                      <ChevronLeft />
                    </DatePicker.PrevTrigger>
                    <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                      <DatePicker.RangeText />
                    </DatePicker.ViewTrigger>
                    <DatePicker.NextTrigger class={styles.NextTrigger}>
                      <ChevronRight />
                    </DatePicker.NextTrigger>
                  </DatePicker.ViewControl>
                  <DatePicker.Table class={styles.Table}>
                    <DatePicker.TableBody class={styles.TableBody}>
                      for (const months of @context.getMonthsGrid(
                        { columns: 4, format: 'short' },
                      ); key months[0].value) {
                        <DatePicker.TableRow class={styles.TableRow}>
                          for (const month of months; key month.value) {
                            <DatePicker.TableCell class={styles.TableCell} value={month.value}>
                              <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                                {month.label}
                              </DatePicker.TableCellTrigger>
                            </DatePicker.TableCell>
                          }
                        </DatePicker.TableRow>
                      }
                    </DatePicker.TableBody>
                  </DatePicker.Table>
                }
              </DatePicker.Context>
            </DatePicker.View>
            <DatePicker.View view="year" class={styles.View}>
              <DatePicker.Context>
                component children({ context }) {
                  <DatePicker.ViewControl class={styles.ViewControl}>
                    <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                      <ChevronLeft />
                    </DatePicker.PrevTrigger>
                    <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                      <DatePicker.RangeText />
                    </DatePicker.ViewTrigger>
                    <DatePicker.NextTrigger class={styles.NextTrigger}>
                      <ChevronRight />
                    </DatePicker.NextTrigger>
                  </DatePicker.ViewControl>
                  <DatePicker.Table class={styles.Table}>
                    <DatePicker.TableBody class={styles.TableBody}>
                      for (const years of @context.getYearsGrid(
                        { columns: 4 },
                      ); key years[0].value) {
                        <DatePicker.TableRow class={styles.TableRow}>
                          for (const year of years; key year.value) {
                            <DatePicker.TableCell class={styles.TableCell} value={year.value}>
                              <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                                {year.label}
                              </DatePicker.TableCellTrigger>
                            </DatePicker.TableCell>
                          }
                        </DatePicker.TableRow>
                      }
                    </DatePicker.TableBody>
                  </DatePicker.Table>
                }
              </DatePicker.Context>
            </DatePicker.View>
          </DatePicker.Content>
        </DatePicker.Positioner>
      </Portal>
    </DatePicker.Root>
    <input type="submit" value="Submit" />
  </form>
}

```

### With Time

Integrate a time input with the date picker using `CalendarDateTime` from `@internationalized/date`. The time input
updates the hour and minute of the selected date value.

**Example: with-time**

```ripple
import { DatePicker, type CalendarDateTime } from 'ark-ripple/date-picker';
import { Portal } from 'ark-ripple/portal';
import { track } from 'ripple';
import { ChevronLeft, ChevronRight, Calendar } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/date-picker.module.css';

export component WithTime() {
  let value = track<CalendarDateTime[]>([]);
  <DatePicker.Root
    class={styles.Root}
    {value}
    onValueChange={(e) => {
      @value = e.value as CalendarDateTime[];
    }}
  >
    <DatePicker.Label class={styles.Label}>{'Label'}</DatePicker.Label>
    <DatePicker.Control class={styles.Control}>
      <DatePicker.Input class={styles.Input} />
      <DatePicker.Trigger class={button.Root} style={{ marginInlineStart: 'auto' }}>
        <Calendar />
      </DatePicker.Trigger>
    </DatePicker.Control>
    <Portal>
      <DatePicker.Positioner>
        <DatePicker.Content class={styles.Content}>
          <DatePicker.View view="day" class={styles.View}>
            <DatePicker.Context>
              component children({ context }) {
                <DatePicker.ViewControl class={styles.ViewControl}>
                  <DatePicker.PrevTrigger class={styles.PrevTrigger}>
                    <ChevronLeft />
                  </DatePicker.PrevTrigger>
                  <DatePicker.ViewTrigger class={styles.ViewTrigger}>
                    <DatePicker.RangeText />
                  </DatePicker.ViewTrigger>
                  <DatePicker.NextTrigger class={styles.NextTrigger}>
                    <ChevronRight />
                  </DatePicker.NextTrigger>
                </DatePicker.ViewControl>
                <DatePicker.Table class={styles.Table}>
                  <DatePicker.TableHead class={styles.TableHead}>
                    <DatePicker.TableRow class={styles.TableRow}>
                      for (const weekDay of @context.weekDays; key weekDay.short) {
                        <DatePicker.TableHeader class={styles.TableHeader}>
                          {weekDay.short}
                        </DatePicker.TableHeader>
                      }
                    </DatePicker.TableRow>
                  </DatePicker.TableHead>
                  <DatePicker.TableBody class={styles.TableBody}>
                    for (const week of @context.weeks; key week[0].toString()) {
                      <DatePicker.TableRow class={styles.TableRow}>
                        for (const day of week; key day.toString()) {
                          <DatePicker.TableCell class={styles.TableCell} value={day}>
                            <DatePicker.TableCellTrigger class={styles.TableCellTrigger}>
                              {day.day}
                            </DatePicker.TableCellTrigger>
                          </DatePicker.TableCell>
                        }
                      </DatePicker.TableRow>
                    }
                  </DatePicker.TableBody>
                </DatePicker.Table>
                <DatePicker.TimeInput
                  value={@context.value[0]}
                  onValueChange={(e) => {
                    @value = [e.value as CalendarDateTime];
                  }}
                />
              }
            </DatePicker.Context>
          </DatePicker.View>
        </DatePicker.Content>
      </DatePicker.Positioner>
    </Portal>
  </DatePicker.Root>
}

```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `closeOnSelect` | `boolean` | No | Whether the calendar should close after the date selection is complete.
This is ignored when the selection mode is `multiple`. |
| `createCalendar` | `(identifier: CalendarIdentifier) => Calendar` | No | A function that creates a Calendar object for a given calendar identifier.
Enables non-Gregorian calendar support (Persian, Buddhist, Islamic, etc.)
without bundling all calendars by default. |
| `defaultFocusedValue` | `DateValue` | No | The initial focused date when rendered.
Use when you don't need to control the focused date of the date picker. |
| `defaultOpen` | `boolean` | No | The initial open state of the date picker when rendered.
Use when you don't need to control the open state of the date picker. |
| `defaultValue` | `DateValue[]` | No | The initial selected date(s) when rendered.
Use when you don't need to control the selected date(s) of the date picker. |
| `defaultView` | `DateView` | No | The default view of the calendar |
| `disabled` | `boolean` | No | Whether the calendar is disabled. |
| `fixedWeeks` | `boolean` | No | Whether the calendar should have a fixed number of weeks.
This renders the calendar with 6 weeks instead of 5 or 6. |
| `focusedValue` | `DateValue` | No | The controlled focused date. |
| `format` | `(date: DateValue, details: LocaleDetails) => string` | No | The format of the date to display in the input. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{ root: string; label: (index: number) => string; table: (id: string) => string; tableHeader: (id: string) => string; tableBody: (id: string) => string; tableRow: (id: string) => string; content: string; ... 10 more ...; positioner: string; }>` | No | The ids of the elements in the date picker. Useful for composition. |
| `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame |
| `inline` | `boolean` | No | Whether to render the date picker inline |
| `invalid` | `boolean` | No | Whether the date picker is invalid |
| `isDateUnavailable` | `(date: DateValue, locale: string) => boolean` | No | Returns whether a date of the calendar is available. |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `locale` | `string` | No | The locale (BCP 47 language tag) to use when formatting the date. |
| `max` | `DateValue` | No | The maximum date that can be selected. |
| `maxSelectedDates` | `number` | No | The maximum number of dates that can be selected.
This is only applicable when `selectionMode` is `multiple`. |
| `maxView` | `DateView` | No | The maximum view of the calendar |
| `min` | `DateValue` | No | The minimum date that can be selected. |
| `minView` | `DateView` | No | The minimum view of the calendar |
| `name` | `string` | No | The `name` attribute of the input element. |
| `numOfMonths` | `number` | No | The number of months to display. |
| `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state |
| `onFocusChange` | `(details: FocusChangeDetails) => void` | No | Function called when the focused date changes. |
| `onOpenChange` | `(details: OpenChangeDetails) => void` | No | Function called when the calendar opens or closes. |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | Function called when the value changes. |
| `onViewChange` | `(details: ViewChangeDetails) => void` | No | Function called when the view changes. |
| `onVisibleRangeChange` | `(details: VisibleRangeChangeDetails) => void` | No | Function called when the visible range changes. |
| `open` | `boolean` | No | The controlled open state of the date picker |
| `openOnClick` | `boolean` | No | Whether to open the calendar when the input is clicked. |
| `outsideDaySelectable` | `boolean` | No | Whether day outside the visible range can be selected. |
| `parse` | `(value: string, details: LocaleDetails) => DateValue | undefined` | No | Function to parse the date from the input back to a DateValue. |
| `placeholder` | `string` | No | The placeholder text to display in the input. |
| `positioning` | `PositioningOptions` | No | The user provided options used to position the date picker content |
| `present` | `boolean` | No | Whether the node is present (controlled by the user) |
| `readOnly` | `boolean` | No | Whether the calendar is read-only. |
| `required` | `boolean` | No | Whether the date picker is required |
| `selectionMode` | `SelectionMode` | No | The selection mode of the calendar.
- `single` - only one date can be selected
- `multiple` - multiple dates can be selected
- `range` - a range of dates can be selected |
| `showWeekNumbers` | `boolean` | No | Whether to show the week number column in the day view. |
| `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. |
| `startOfWeek` | `number` | No | The first day of the week.
 `0` - Sunday
 `1` - Monday
 `2` - Tuesday
 `3` - Wednesday
 `4` - Thursday
 `5` - Friday
 `6` - Saturday |
| `timeZone` | `string` | No | The time zone to use |
| `translations` | `IntlTranslations` | No | The localized messages to use. |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |
| `value` | `DateValue[]` | No | The controlled selected date(s). |
| `view` | `DateView` | No | The view of the calendar |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | date-picker |
| `[data-part]` | root |
| `[data-state]` | "open" | "closed" |
| `[data-disabled]` | Present when disabled |
| `[data-readonly]` | Present when read-only |
| `[data-empty]` | Present when the content is empty |


**ClearTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | date-picker |
| `[data-part]` | content |
| `[data-state]` | "open" | "closed" |
| `[data-nested]` | popover |
| `[data-has-nested]` | popover |
| `[data-placement]` | The placement of the content |
| `[data-inline]` | Present when the content is inline |


**Content CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--layer-index` | The index of the dismissable in the layer stack |
| `--nested-layer-count` | The number of nested date-pickers |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | date-picker |
| `[data-part]` | control |
| `[data-disabled]` | Present when disabled |
| `[data-placeholder-shown]` | Present when placeholder is shown |


**Input Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `fixOnBlur` | `boolean` | No | Whether to fix the input value on blur. |
| `index` | `number` | No | The index of the input to focus. |


**Input Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | date-picker |
| `[data-part]` | input |
| `[data-index]` | The index of the item |
| `[data-state]` | "open" | "closed" |
| `[data-placeholder-shown]` | Present when placeholder is shown |
| `[data-invalid]` | Present when invalid |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | date-picker |
| `[data-part]` | label |
| `[data-state]` | "open" | "closed" |
| `[data-index]` | The index of the item |
| `[data-disabled]` | Present when disabled |
| `[data-readonly]` | Present when read-only |


**MonthSelect Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**NextTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**NextTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | date-picker |
| `[data-part]` | next-trigger |
| `[data-disabled]` | Present when disabled |


**Positioner Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Positioner CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--reference-width` | The width of the reference element |
| `--reference-height` | The height of the root |
| `--available-width` | The available width in viewport |
| `--available-height` | The available height in viewport |
| `--x` | The x position for transform |
| `--y` | The y position for transform |
| `--z-index` | The z-index value |
| `--transform-origin` | The transform origin for animations |


**PresetTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `PresetTriggerValue` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**PrevTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**PrevTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | date-picker |
| `[data-part]` | prev-trigger |
| `[data-disabled]` | Present when disabled |


**RangeText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseDatePickerReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state |
| `present` | `boolean` | No | Whether the node is present (controlled by the user) |
| `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


**TableBody Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**TableBody Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | date-picker |
| `[data-part]` | table-body |
| `[data-view]` | The view of the tablebody |
| `[data-disabled]` | Present when disabled |


**TableCell Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `number | DateValue` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `columns` | `number` | No |  |
| `disabled` | `boolean` | No |  |
| `visibleRange` | `VisibleRange` | No |  |


**TableCellTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**TableHead Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**TableHead Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | date-picker |
| `[data-part]` | table-head |
| `[data-view]` | The view of the tablehead |
| `[data-disabled]` | Present when disabled |


**TableHeader Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**TableHeader Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | date-picker |
| `[data-part]` | table-header |
| `[data-view]` | The view of the tableheader |
| `[data-disabled]` | Present when disabled |


**Table Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `columns` | `number` | No |  |


**Table Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | date-picker |
| `[data-part]` | table |
| `[data-columns]` |  |
| `[data-view]` | The view of the table |


**TableRow Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**TableRow Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | date-picker |
| `[data-part]` | table-row |
| `[data-disabled]` | Present when disabled |
| `[data-view]` | The view of the tablerow |


**Trigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | date-picker |
| `[data-part]` | trigger |
| `[data-placement]` | The placement of the trigger |
| `[data-state]` | "open" | "closed" |
| `[data-placeholder-shown]` | Present when placeholder is shown |


**ValueText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `placeholder` | `string` | No | Text to display when no date is selected. |
| `separator` | `string` | No | The separator to use between multiple date values when using default rendering. |


**ValueTextRender Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes |  |
| `remove` | `() => void` | Yes |  |
| `value` | `DateValue` | Yes |  |
| `valueAsString` | `string` | Yes |  |


**ViewControl Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ViewControl Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | date-picker |
| `[data-part]` | view-control |
| `[data-view]` | The view of the viewcontrol |


**View Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `view` | `DateView` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**View Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | date-picker |
| `[data-part]` | view |
| `[data-view]` | The view of the view |


**ViewTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ViewTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | date-picker |
| `[data-part]` | view-trigger |
| `[data-view]` | The view of the viewtrigger |


**WeekNumberCell Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `week` | `DateValue[]` | Yes |  |
| `weekIndex` | `number` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**WeekNumberCell Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | date-picker |
| `[data-part]` | week-number-cell |
| `[data-view]` | The view of the weeknumbercell |
| `[data-week-index]` |  |
| `[data-type]` | The type of the item |
| `[data-disabled]` | Present when disabled |


**WeekNumberHeaderCell Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**WeekNumberHeaderCell Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | date-picker |
| `[data-part]` | week-number-header-cell |
| `[data-view]` | The view of the weeknumberheadercell |
| `[data-type]` | The type of the item |
| `[data-disabled]` | Present when disabled |


**YearSelect Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `focused` | `boolean` | Whether the input is focused |
| `open` | `boolean` | Whether the date picker is open |
| `disabled` | `boolean` | Whether the date picker is disabled |
| `invalid` | `boolean` | Whether the date picker is invalid |
| `readOnly` | `boolean` | Whether the date picker is read-only |
| `inline` | `boolean` | Whether the date picker is rendered inline |
| `numOfMonths` | `number` | The number of months to display |
| `showWeekNumbers` | `boolean` | Whether the week number column is shown in the day view |
| `selectionMode` | `SelectionMode` | The selection mode (single, multiple, or range) |
| `maxSelectedDates` | `number` | The maximum number of dates that can be selected (only for multiple selection mode). |
| `isMaxSelected` | `boolean` | Whether the maximum number of selected dates has been reached. |
| `view` | `DateView` | The current view of the date picker |
| `getWeekNumber` | `(week: DateValue[]) => number` | Returns the ISO 8601 week number (1-53) for the given week (array of dates). |
| `getDaysInWeek` | `(week: number, from?: DateValue) => DateValue[]` | Returns an array of days in the week index counted from the provided start date, or the first visible date if not given. |
| `getOffset` | `(duration: DateDuration) => DateValueOffset` | Returns the offset of the month based on the provided number of months. |
| `getRangePresetValue` | `(value: DateRangePreset) => DateValue[]` | Returns the range of dates based on the provided date range preset. |
| `getMonthWeeks` | `(from?: DateValue) => DateValue[][]` | Returns the weeks of the month from the provided date. Represented as an array of arrays of dates. |
| `isUnavailable` | `(date: DateValue) => boolean` | Returns whether the provided date is available (or can be selected) |
| `weeks` | `DateValue[][]` | The weeks of the month. Represented as an array of arrays of dates. |
| `weekDays` | `WeekDay[]` | The days of the week. Represented as an array of strings. |
| `visibleRange` | `VisibleRange` | The visible range of dates. |
| `visibleRangeText` | `VisibleRangeText` | The human readable text for the visible range of dates. |
| `value` | `DateValue[]` | The selected date. |
| `valueAsDate` | `Date[]` | The selected date as a Date object. |
| `valueAsString` | `string[]` | The selected date as a string. |
| `focusedValue` | `DateValue` | The focused date. |
| `focusedValueAsDate` | `Date` | The focused date as a Date object. |
| `focusedValueAsString` | `string` | The focused date as a string. |
| `selectToday` | `VoidFunction` | Sets the selected date to today. |
| `setValue` | `(values: DateValue[]) => void` | Sets the selected date to the given date. |
| `setTime` | `(time: Time, index?: number) => void` | Sets the time for a specific date value.
Converts CalendarDate to CalendarDateTime if needed. |
| `setFocusedValue` | `(value: DateValue) => void` | Sets the focused date to the given date. |
| `clearValue` | `(options?: { focus?: boolean; }) => void` | Clears the selected date(s). |
| `setOpen` | `(open: boolean) => void` | Function to open or close the calendar. |
| `focusMonth` | `(month: number) => void` | Function to set the selected month. |
| `focusYear` | `(year: number) => void` | Function to set the selected year. |
| `getYears` | `() => Cell[]` | Returns the months of the year |
| `getYearsGrid` | `(props?: YearGridProps) => YearGridValue` | Returns the years of the decade based on the columns.
Represented as an array of arrays of years. |
| `getDecade` | `() => Range<number>` | Returns the start and end years of the decade. |
| `getMonths` | `(props?: MonthFormatOptions) => Cell[]` | Returns the months of the year |
| `getMonthsGrid` | `(props?: MonthGridProps) => MonthGridValue` | Returns the months of the year based on the columns.
Represented as an array of arrays of months. |
| `format` | `(value: DateValue, opts?: Intl.DateTimeFormatOptions) => string` | Formats the given date value based on the provided options. |
| `setView` | `(view: DateView) => void` | Sets the view of the date picker. |
| `goToNext` | `VoidFunction` | Goes to the next month/year/decade. |
| `goToPrev` | `VoidFunction` | Goes to the previous month/year/decade. |
| `getDayTableCellState` | `(props: DayTableCellProps) => DayTableCellState` | Returns the state details for a given cell. |
| `getMonthTableCellState` | `(props: TableCellProps) => TableCellState` | Returns the state details for a given month cell. |
| `getYearTableCellState` | `(props: TableCellProps) => TableCellState` | Returns the state details for a given year cell. |


## Accessibility

### Keyboard Support

**`ArrowLeft`**
Description: Moves focus to the previous day within the current week.

**`ArrowRight`**
Description: Moves focus to the next day within the current week.

**`ArrowUp`**
Description: Moves focus to the same day of the week in the previous week.

**`ArrowDown`**
Description: Moves focus to the same day of the week in the next week.

**`Home`**
Description: Moves focus to the first day of the current month.

**`End`**
Description: Moves focus to the last day of the current month.

**`PageUp`**
Description: Moves focus to the same day of the month in the previous month.

**`PageDown`**
Description: Moves focus to the same day of the month in the next month.

**`Enter`**
Description: Selects the focused date and closes the date picker.

**`Esc`**
Description: Closes the date picker without selecting any date.


# Dialog 



## Anatomy



```tsx
<Dialog.Root>
  <Dialog.Trigger />
  <Dialog.Backdrop />
  <Dialog.Positioner>
    <Dialog.Content>
      <Dialog.Title />
      <Dialog.Description />
      <Dialog.CloseTrigger />
    </Dialog.Content>
  </Dialog.Positioner>
</Dialog.Root>
```

## Examples

**Example: basic**

```ripple
import { Dialog } from 'ark-ripple/dialog';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import styles from 'styles/dialog.module.css';

export component Basic() {
  <Dialog.Root>
    <Dialog.Trigger class={button.Root}>{'Open Dialog'}</Dialog.Trigger>
    <Portal>
      <Dialog.Backdrop class={styles.Backdrop} />
      <Dialog.Positioner class={styles.Positioner}>
        <Dialog.Content class={styles.Content}>
          <Dialog.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Dialog.CloseTrigger>
          <Dialog.Title class={styles.Title}>{'Welcome Back'}</Dialog.Title>
          <Dialog.Description class={styles.Description}>
            {'Sign in to your account to continue.'}
          </Dialog.Description>
        </Dialog.Content>
      </Dialog.Positioner>
    </Portal>
  </Dialog.Root>
}

```

### Controlled

Manage the dialog state using the `open` and `onOpenChange` props.

**Example: controlled**

```ripple
import { Dialog } from 'ark-ripple/dialog';
import { Portal } from 'ark-ripple/portal';
import { track } from 'ripple';
import button from 'styles/button.module.css';
import styles from 'styles/dialog.module.css';

export component Controlled() {
  let open = track(false);

  <Dialog.Root
    {open}
    onOpenChange={(e) => {
      @open = e.open;
    }}
  >
    <Dialog.Trigger class={button.Root}>{'Open Dialog'}</Dialog.Trigger>
    <Portal>
      <Dialog.Backdrop class={styles.Backdrop} />
      <Dialog.Positioner class={styles.Positioner}>
        <Dialog.Content class={styles.Content}>
          <Dialog.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Dialog.CloseTrigger>
          <Dialog.Title class={styles.Title}>{'Session Settings'}</Dialog.Title>
          <Dialog.Description class={styles.Description}>
            {'Manage your session preferences and security options.'}
          </Dialog.Description>
        </Dialog.Content>
      </Dialog.Positioner>
    </Portal>
  </Dialog.Root>
}

```

### Root Provider

An alternative way to control the dialog is to use the `RootProvider` component and the `useDialog` hook. This way you
can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { Dialog, useDialog } from 'ark-ripple/dialog';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import styles from 'styles/dialog.module.css';

export component RootProvider() {
  const dialog = useDialog();

  <div class="stack">
    <button class={button.Root} onClick={() => @dialog.setOpen(true)}>
      {'Dialog is '}
      {@dialog.open ? 'open' : 'closed'}
    </button>
    <Dialog.RootProvider value={dialog}>
      <Portal>
        <Dialog.Backdrop class={styles.Backdrop} />
        <Dialog.Positioner class={styles.Positioner}>
          <Dialog.Content class={styles.Content}>
            <Dialog.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Dialog.CloseTrigger>
            <Dialog.Title class={styles.Title}>{'Controlled Externally'}</Dialog.Title>
            <Dialog.Description class={styles.Description}>
              {'This dialog is controlled via the useDialog hook.'}
            </Dialog.Description>
          </Dialog.Content>
        </Dialog.Positioner>
      </Portal>
    </Dialog.RootProvider>
  </div>
}

```

### Alert Dialog

For critical confirmations or destructive actions, use `role="alertdialog"`. Alert dialogs differ from regular dialogs
in important ways:

- **Automatic focus**: The close/cancel button receives focus when opened, prioritizing the safest action
- **Requires explicit dismissal**: Cannot be closed by clicking outside, only via button clicks or Escape key

**Example: alert-dialog**

```ripple
import { Dialog } from 'ark-ripple/dialog';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import styles from 'styles/dialog.module.css';

export component AlertDialog() {
  <Dialog.Root role="alertdialog">
    <Dialog.Trigger class={button.Root}>{'Delete Account'}</Dialog.Trigger>
    <Portal>
      <Dialog.Backdrop class={styles.Backdrop} />
      <Dialog.Positioner class={styles.Positioner}>
        <Dialog.Content class={styles.Content}>
          <Dialog.Title class={styles.Title}>{'Are you absolutely sure?'}</Dialog.Title>
          <Dialog.Description class={styles.Description}>
            {'This action cannot be undone. This will permanently delete your account and remove your data from our servers.'}
          </Dialog.Description>
          <div class={styles.Actions}>
            <Dialog.CloseTrigger class={button.Root}>{'Cancel'}</Dialog.CloseTrigger>
            <button class={button.Root} data-variant="solid">{'Delete Account'}</button>
          </div>
        </Dialog.Content>
      </Dialog.Positioner>
    </Portal>
  </Dialog.Root>
}

```

### Lazy Mount

Use `lazyMount` to render dialog content only when first opened. Combine with `unmountOnExit` to unmount when closed,
freeing up resources.

**Example: lazy-mount**

```ripple
import { Dialog } from 'ark-ripple/dialog';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import styles from 'styles/dialog.module.css';

export component LazyMount() {
  <Dialog.Root lazyMount unmountOnExit>
    <Dialog.Trigger class={button.Root}>{'Open Dialog'}</Dialog.Trigger>
    <Portal>
      <Dialog.Backdrop class={styles.Backdrop} />
      <Dialog.Positioner class={styles.Positioner}>
        <Dialog.Content class={styles.Content}>
          <Dialog.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Dialog.CloseTrigger>
          <Dialog.Title class={styles.Title}>{'Lazy Loaded'}</Dialog.Title>
          <Dialog.Description class={styles.Description}>
            {'This dialog content is only mounted when opened and unmounts on close.'}
          </Dialog.Description>
        </Dialog.Content>
      </Dialog.Positioner>
    </Portal>
  </Dialog.Root>
}

```

### Initial Focus

Use `initialFocusEl` to control which element receives focus when the dialog opens.

**Example: initial-focus**

```ripple
import { Dialog } from 'ark-ripple/dialog';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import field from 'styles/field.module.css';
import styles from 'styles/dialog.module.css';

export component InitialFocus() {
  let inputEl: HTMLInputElement;

  <Dialog.Root initialFocusEl={() => inputEl}>
    <Dialog.Trigger class={button.Root}>{'Open Dialog'}</Dialog.Trigger>
    <Portal>
      <Dialog.Backdrop class={styles.Backdrop} />
      <Dialog.Positioner class={styles.Positioner}>
        <Dialog.Content class={styles.Content}>
          <Dialog.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Dialog.CloseTrigger>
          <Dialog.Title class={styles.Title}>{'Edit Profile'}</Dialog.Title>
          <Dialog.Description class={styles.Description}>
            {'The first input will be focused when the dialog opens.'}
          </Dialog.Description>
          <div class={styles.Body}>
            <input
              {ref (el: HTMLInputElement) => {
                inputEl = el;
              }}
              class={field.Input}
              placeholder="Enter your name..."
            />
            <input class={field.Input} placeholder="Enter your email..." />
          </div>
        </Dialog.Content>
      </Dialog.Positioner>
    </Portal>
  </Dialog.Root>
}

```

### Final Focus

Use `finalFocusEl` to control which element receives focus when the dialog closes. Defaults to the trigger element.

**Example: final-focus**

```ripple
import { Dialog } from 'ark-ripple/dialog';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import styles from 'styles/dialog.module.css';

export component FinalFocus() {
  let finalRef: HTMLButtonElement;

  <div class="stack">
    <button
      class={button.Root}
      {ref (el: HTMLButtonElement) => {
        finalRef = el;
      }}
    >
      {'I will receive focus when dialog closes'}
    </button>
    <Dialog.Root finalFocusEl={() => finalRef}>
      <Dialog.Trigger class={button.Root}>{'Open Dialog'}</Dialog.Trigger>
      <Portal>
        <Dialog.Backdrop class={styles.Backdrop} />
        <Dialog.Positioner class={styles.Positioner}>
          <Dialog.Content class={styles.Content}>
            <Dialog.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Dialog.CloseTrigger>
            <Dialog.Title class={styles.Title}>{'Focus Redirect'}</Dialog.Title>
            <Dialog.Description class={styles.Description}>
              {'When this dialog closes, focus will return to the button above instead of the trigger.'}
            </Dialog.Description>
          </Dialog.Content>
        </Dialog.Positioner>
      </Portal>
    </Dialog.Root>
  </div>
}

```

### Non-Modal

Use `modal={false}` to allow interaction with elements outside the dialog. Disables focus trapping and scroll
prevention.

**Example: non-modal**

```ripple
import { Dialog } from 'ark-ripple/dialog';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import styles from 'styles/dialog.module.css';

export component NonModal() {
  <Dialog.Root modal={false}>
    <Dialog.Trigger class={button.Root}>{'Open Non-Modal Dialog'}</Dialog.Trigger>
    <Portal>
      <Dialog.Backdrop class={styles.Backdrop} />
      <Dialog.Positioner class={styles.Positioner}>
        <Dialog.Content class={styles.Content}>
          <Dialog.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Dialog.CloseTrigger>
          <Dialog.Title class={styles.Title}>{'Non-Modal Dialog'}</Dialog.Title>
          <Dialog.Description class={styles.Description}>
            {'This dialog allows interaction with elements outside. You can click buttons, select text, and interact with the page behind it.'}
          </Dialog.Description>
        </Dialog.Content>
      </Dialog.Positioner>
    </Portal>
  </Dialog.Root>
}

```

### Inside Scroll

Make the content area scrollable while keeping header and footer fixed using `maxHeight` and `overflow: auto`.

**Example: inside-scroll**

```ripple
import { Dialog } from 'ark-ripple/dialog';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import styles from 'styles/dialog.module.css';

const CONTENT_SECTIONS = [
  {
    title: '1. Acceptance of Terms',
    body: 'By accessing and using this service, you accept and agree to be bound by the terms and provisions of this agreement.',
  },
  {
    title: '2. Use License',
    body: 'Permission is granted to temporarily use this service for personal, non-commercial purposes only. This is the grant of a license, not a transfer of title.',
  },
  {
    title: '3. User Responsibilities',
    body: 'You are responsible for maintaining the confidentiality of your account and password. You agree to accept responsibility for all activities that occur under your account.',
  },
  {
    title: '4. Privacy Policy',
    body: 'Your use of this service is also governed by our Privacy Policy. Please review our Privacy Policy, which also governs the site and informs users of our data collection practices.',
  },
  {
    title: '5. Limitations',
    body: 'In no event shall we be liable for any damages arising out of the use or inability to use the materials on this service.',
  },
  {
    title: '6. Revisions',
    body: 'We may revise these terms of service at any time without notice. By using this service you are agreeing to be bound by the then current version of these terms.',
  },
  {
    title: '7. Governing Law',
    body: 'These terms and conditions are governed by and construed in accordance with applicable laws and you irrevocably submit to the exclusive jurisdiction of the courts.',
  },
];

export component InsideScroll() {
  <Dialog.Root>
    <Dialog.Trigger class={button.Root}>{'Open Dialog'}</Dialog.Trigger>
    <Portal>
      <Dialog.Backdrop class={styles.Backdrop} />
      <Dialog.Positioner class={styles.Positioner}>
        <Dialog.Content
          class={styles.Content}
          style={{ maxHeight: 'min(32rem, calc(100vh - 4rem))' }}
        >
          <Dialog.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Dialog.CloseTrigger>
          <Dialog.Title class={styles.Title}>{'Terms of Service'}</Dialog.Title>
          <Dialog.Description class={styles.Description}>
            {'Please review our terms before continuing.'}
          </Dialog.Description>
          <div class={styles.ScrollContainer}>
            for (const item of CONTENT_SECTIONS; key item.title) {
              <section class={styles.ScrollSection}>
                <h3>{item.title}</h3>
                <p>{item.body}</p>
              </section>
            }
          </div>
          <div class={styles.Actions}>
            <Dialog.CloseTrigger class={button.Root}>{'Decline'}</Dialog.CloseTrigger>
            <Dialog.CloseTrigger class={button.Root} data-variant="solid">
              {'Accept'}
            </Dialog.CloseTrigger>
          </div>
        </Dialog.Content>
      </Dialog.Positioner>
    </Portal>
  </Dialog.Root>
}

```

### Outside Scroll

Make the positioner scrollable so the dialog can extend beyond the viewport.

**Example: outside-scroll**

```ripple
import { Dialog } from 'ark-ripple/dialog';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import styles from 'styles/dialog.module.css';

const CONTENT_SECTIONS = [
  {
    title: '1. Information We Collect',
    body: 'We collect information you provide directly, such as when you create an account, make a purchase, or contact us for support. This may include your name, email address, and payment information.',
  },
  {
    title: '2. How We Use Your Information',
    body: 'We use the information we collect to provide and improve our services, process transactions, send communications, and personalize your experience.',
  },
  {
    title: '3. Information Sharing',
    body: 'We do not sell your personal information. We may share information with service providers who assist in our operations, or when required by law.',
  },
  {
    title: '4. Data Security',
    body: 'We implement appropriate technical and organizational measures to protect your personal information against unauthorized access, alteration, or destruction.',
  },
  {
    title: '5. Your Rights',
    body: 'You have the right to access, correct, or delete your personal information. You may also opt out of marketing communications at any time.',
  },
  {
    title: '6. Cookies and Tracking',
    body: 'We use cookies and similar technologies to enhance your experience, analyze usage patterns, and deliver targeted content. You can manage cookie preferences in your browser settings.',
  },
  {
    title: '7. Third-Party Services',
    body: 'Our service may contain links to third-party websites. We are not responsible for the privacy practices of these external sites.',
  },
  {
    title: '8. Children Privacy',
    body: 'Our services are not directed to children under 13. We do not knowingly collect personal information from children without parental consent.',
  },
  {
    title: '9. International Transfers',
    body: 'Your information may be transferred to and processed in countries other than your own. We ensure appropriate safeguards are in place for such transfers.',
  },
  {
    title: '10. Changes to This Policy',
    body: 'We may update this privacy policy from time to time. We will notify you of significant changes by posting a notice on our website or sending you an email.',
  },
  {
    title: '11. Data Retention',
    body: 'We retain your personal information for as long as necessary to fulfill the purposes outlined in this policy, unless a longer retention period is required by law.',
  },
  {
    title: '12. Contact Us',
    body: 'If you have questions about this privacy policy or our data practices, please contact our privacy team through the support channels provided on our website.',
  },
];

export component OutsideScroll() {
  let contentRef: HTMLDivElement | null = null;

  <Dialog.Root initialFocusEl={() => contentRef}>
    <Dialog.Trigger class={button.Root}>{'Open Dialog'}</Dialog.Trigger>
    <Portal>
      <Dialog.Backdrop class={styles.Backdrop} />
      <Dialog.Positioner class={styles.OutsideScrollPositioner}>
        <Dialog.Content
          {ref (el: HTMLDivElement) => {
            contentRef = el;
          }}
          class={styles.Content}
          style={{ margin: '4rem auto', maxHeight: 'none' }}
        >
          <Dialog.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Dialog.CloseTrigger>
          <Dialog.Title class={styles.Title}>{'Privacy Policy'}</Dialog.Title>
          <Dialog.Description class={styles.Description}>
            {'This layout allows the dialog to extend beyond the viewport while keeping the outer container scrollable.'}
          </Dialog.Description>
          <div class={styles.Body}>
            for (const item of CONTENT_SECTIONS; key item.title) {
              <section class={styles.ScrollSection}>
                <h3>{item.title}</h3>
                <p>{item.body}</p>
              </section>
            }
          </div>
        </Dialog.Content>
      </Dialog.Positioner>
    </Portal>
  </Dialog.Root>
}

```

### Context

Access the dialog's state and methods with `Dialog.Context` or the `useDialogContext` hook.

**Example: context**

```ripple
import { Dialog } from 'ark-ripple/dialog';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import styles from 'styles/dialog.module.css';

export component Context() {
  <Dialog.Root>
    <Dialog.Trigger class={button.Root}>{'Open Dialog'}</Dialog.Trigger>
    <Portal>
      <Dialog.Backdrop class={styles.Backdrop} />
      <Dialog.Positioner class={styles.Positioner}>
        <Dialog.Content class={styles.Content}>
          <Dialog.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Dialog.CloseTrigger>
          <Dialog.Title class={styles.Title}>{'Status'}</Dialog.Title>
          <Dialog.Description class={styles.Description}>
            <Dialog.Context>
              component children({ context }) {
                <span>
                  {'Dialog is '}
                  {@context.open ? 'open' : 'closed'}
                </span>
              }
            </Dialog.Context>
          </Dialog.Description>
        </Dialog.Content>
      </Dialog.Positioner>
    </Portal>
  </Dialog.Root>
}

```

### Open from Menu

Open a dialog imperatively from a menu item using the `onClick` handler.

**Example: open-from-menu**

```ripple
import { Dialog } from 'ark-ripple/dialog';
import { Menu } from 'ark-ripple/menu';
import { Portal } from 'ark-ripple/portal';
import { ChevronDown, X } from 'lucide-ripple';
import { track } from 'ripple';
import dialog from 'styles/dialog.module.css';
import menu from 'styles/menu.module.css';

export component OpenFromMenu() {
  let open = track(false);

  <Menu.Root>
    <Menu.Trigger class={menu.Trigger}>
      {'Actions'}
      <Menu.Indicator class={menu.Indicator}>
        <ChevronDown />
      </Menu.Indicator>
    </Menu.Trigger>
    <Portal>
      <Menu.Positioner>
        <Menu.Content class={menu.Content}>
          <Menu.Item class={menu.Item} value="edit">{'Edit'}</Menu.Item>
          <Menu.Item class={menu.Item} value="duplicate">{'Duplicate'}</Menu.Item>
          <Menu.Separator class={menu.Separator} />
          <Menu.Item
            class={menu.Item}
            value="delete"
            onSelect={() => {
              @open = true;
            }}
          >
            {'Delete...'}
          </Menu.Item>
        </Menu.Content>
      </Menu.Positioner>
    </Portal>
  </Menu.Root>

  <Dialog.Root
    {open}
    onOpenChange={(e) => {
      @open = e.open;
    }}
    role="alertdialog"
  >
    <Portal>
      <Dialog.Backdrop class={dialog.Backdrop} />
      <Dialog.Positioner class={dialog.Positioner}>
        <Dialog.Content class={dialog.Content}>
          <Dialog.Title class={dialog.Title}>{'Confirm Delete'}</Dialog.Title>
          <Dialog.Description class={dialog.Description}>
            {'Are you sure you want to delete this item? This action cannot be undone.'}
          </Dialog.Description>
          <Dialog.CloseTrigger class={dialog.CloseTrigger}>
            <X />
          </Dialog.CloseTrigger>
        </Dialog.Content>
      </Dialog.Positioner>
    </Portal>
  </Dialog.Root>
}

```

### Nested

Nest dialogs within one another. The parent receives `data-has-nested` and `--nested-layer-count` CSS variable for
styling effects like zoom-out:

```css
[data-part='content'][data-has-nested] {
  transform: scale(calc(1 - var(--nested-layer-count) * 0.05));
}
```

**Example: nested**

```ripple
import { Dialog, useDialog } from 'ark-ripple/dialog';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import styles from 'styles/dialog.module.css';

export component Nested() {
  const parentDialog = useDialog();
  const childDialog = useDialog();

  <div class="stack">
    <button class={button.Root} onClick={() => @parentDialog.setOpen(true)}>
      {'Open Parent Dialog'}
    </button>

    <Dialog.RootProvider value={parentDialog}>
      <Portal>
        <Dialog.Backdrop class={styles.Backdrop} />
        <Dialog.Positioner class={styles.Positioner}>
          <Dialog.Content class={styles.Content}>
            <Dialog.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Dialog.CloseTrigger>
            <Dialog.Title class={styles.Title}>{'Parent Dialog'}</Dialog.Title>
            <Dialog.Description class={styles.Description}>
              {'This is the parent dialog.'}
            </Dialog.Description>
            <div class={styles.Body}>
              <button class={button.Root} onClick={() => @childDialog.setOpen(true)}>
                {'Open Nested Dialog'}
              </button>
            </div>
          </Dialog.Content>
        </Dialog.Positioner>
      </Portal>
    </Dialog.RootProvider>

    <Dialog.RootProvider value={childDialog}>
      <Portal>
        <Dialog.Backdrop class={styles.Backdrop} />
        <Dialog.Positioner class={styles.Positioner}>
          <Dialog.Content class={styles.Content}>
            <Dialog.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Dialog.CloseTrigger>
            <Dialog.Title class={styles.Title}>{'Nested Dialog'}</Dialog.Title>
            <Dialog.Description class={styles.Description}>
              {'This dialog is nested within the parent.'}
            </Dialog.Description>
          </Dialog.Content>
        </Dialog.Positioner>
      </Portal>
    </Dialog.RootProvider>
  </div>
}

```

### Confirmation

Intercept close attempts to show confirmation prompts, preventing data loss from unsaved changes.

**Example: confirmation**

```ripple
import { Dialog, useDialog } from 'ark-ripple/dialog';
import { Portal } from 'ark-ripple/portal';
import { track } from 'ripple';
import button from 'styles/button.module.css';
import field from 'styles/field.module.css';
import styles from 'styles/dialog.module.css';

export component Confirmation() {
  let formContent = track('');
  let isParentDialogOpen = track(false);

  const confirmDialog = useDialog();

  let parentDialogProps = track(
    () => ({
      open: isParentDialogOpen,
      onOpenChange: (details) => {
        if (!details.open && @formContent.trim()) {
          @confirmDialog.setOpen(true);
        } else {
          @isParentDialogOpen = details.open;
        }
      },
    }),
  );

  const parentDialog = useDialog(parentDialogProps);

  const handleConfirmClose = () => {
    @formContent = '';
    const childSetter = @confirmDialog.setOpen;
    const parentSetter = @parentDialog.setOpen;
    childSetter(false);
    parentSetter(false);
  };

  <div class="stack">
    <button class={button.Root} onClick={() => @parentDialog.setOpen(true)}>{'Open Form'}</button>

    <Dialog.RootProvider value={parentDialog}>
      <Portal>
        <Dialog.Backdrop class={styles.Backdrop} />
        <Dialog.Positioner class={styles.Positioner}>
          <Dialog.Content class={styles.Content}>
            <Dialog.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Dialog.CloseTrigger>
            <Dialog.Title class={styles.Title}>{'Edit Content'}</Dialog.Title>
            <Dialog.Description class={styles.Description}>
              {'Make changes to your content. You\'ll be asked to confirm before closing if there are unsaved changes.'}
            </Dialog.Description>
            <div class={styles.Body}>
              <textarea
                class={field.Textarea}
                value={@formContent}
                onInput={(e) => {
                  @formContent = e.target.value;
                }}
                placeholder="Enter some text..."
                rows={4}
              />
            </div>
          </Dialog.Content>
        </Dialog.Positioner>
      </Portal>
    </Dialog.RootProvider>

    <Dialog.RootProvider value={confirmDialog}>
      <Portal>
        <Dialog.Backdrop class={styles.Backdrop} />
        <Dialog.Positioner class={styles.Positioner}>
          <Dialog.Content class={styles.Content}>
            <Dialog.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Dialog.CloseTrigger>
            <Dialog.Title class={styles.Title}>{'Unsaved Changes'}</Dialog.Title>
            <Dialog.Description class={styles.Description}>
              {'You have unsaved changes. Are you sure you want to close without saving?'}
            </Dialog.Description>
            <div class={styles.Actions}>
              <button class={button.Root} onClick={() => @confirmDialog.setOpen(false)}>
                {'Keep Editing'}
              </button>
              <button class={button.Root} data-variant="solid" onClick={handleConfirmClose}>
                {'Discard Changes'}
              </button>
            </div>
          </Dialog.Content>
        </Dialog.Positioner>
      </Portal>
    </Dialog.RootProvider>
  </div>
}

```

## Guides

### Close Behavior

- `closeOnEscape={false}` - Prevent closing on <kbd>Escape</kbd>
- `closeOnInteractOutside={false}` - Prevent closing on outside click

For conditional control, use `onEscapeKeyDown` or `onInteractOutside` with `e.preventDefault()`.

### Z-Index Stacking

Use the `--layer-index` CSS variable for z-index management of stacked dialogs:

```css
[data-part='content'] {
  z-index: calc(var(--layer-index));
}
```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `aria-label` | `string` | No | Human readable label for the dialog, in event the dialog title is not rendered |
| `closeOnEscape` | `boolean` | No | Whether to close the dialog when the escape key is pressed |
| `closeOnInteractOutside` | `boolean` | No | Whether to close the dialog when the outside is clicked |
| `defaultOpen` | `boolean` | No | The initial open state of the dialog when rendered.
Use when you don't need to control the open state of the dialog. |
| `finalFocusEl` | `() => MaybeElement` | No | Element to receive focus when the dialog is closed |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{
  trigger: string
  positioner: string
  backdrop: string
  content: string
  closeTrigger: string
  title: string
  description: string
}>` | No | The ids of the elements in the dialog. Useful for composition. |
| `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame |
| `initialFocusEl` | `() => MaybeElement` | No | Element to receive focus when the dialog is opened |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `modal` | `boolean` | No | Whether to prevent pointer interaction outside the element and hide all content below it |
| `onEscapeKeyDown` | `(event: KeyboardEvent) => void` | No | Function called when the escape key is pressed |
| `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state |
| `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component |
| `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component |
| `onOpenChange` | `(details: OpenChangeDetails) => void` | No | Function to call when the dialog's open state changes |
| `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component |
| `onRequestDismiss` | `(event: LayerDismissEvent) => void` | No | Function called when this layer is closed due to a parent layer being closed |
| `open` | `boolean` | No | The controlled open state of the dialog |
| `persistentElements` | `(() => Element | null)[]` | No | Returns the persistent elements that:
- should not have pointer-events disabled
- should not trigger the dismiss event |
| `present` | `boolean` | No | Whether the node is present (controlled by the user) |
| `preventScroll` | `boolean` | No | Whether to prevent scrolling behind the dialog when it's opened |
| `restoreFocus` | `boolean` | No | Whether to restore focus to the element that had focus before the dialog was opened |
| `role` | `'dialog' | 'alertdialog'` | No | The dialog's role |
| `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. |
| `trapFocus` | `boolean` | No | Whether to trap focus inside the dialog when it's opened |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


**Backdrop Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Backdrop Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | dialog |
| `[data-part]` | backdrop |
| `[data-state]` | "open" | "closed" |


**Backdrop CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--layer-index` | The index of the dismissable in the layer stack |


**CloseTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | dialog |
| `[data-part]` | content |
| `[data-state]` | "open" | "closed" |
| `[data-nested]` | dialog |
| `[data-has-nested]` | dialog |


**Content CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--layer-index` | The index of the dismissable in the layer stack |
| `--nested-layer-count` | The number of nested dialogs |


**Description Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Positioner Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseDialogReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state |
| `present` | `boolean` | No | Whether the node is present (controlled by the user) |
| `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


**Title Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | dialog |
| `[data-part]` | trigger |
| `[data-state]` | "open" | "closed" |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `open` | `boolean` | Whether the dialog is open |
| `setOpen` | `(open: boolean) => void` | Function to open or close the dialog |


## Accessibility

Complies with the [Dialog WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/).

### Keyboard Support

**`Enter`**
Description: When focus is on the trigger, opens the dialog.

**`Tab`**
Description: Moves focus to the next focusable element within the content. Focus is trapped within the dialog.

**`Shift + Tab`**
Description: Moves focus to the previous focusable element. Focus is trapped within the dialog.

**`Esc`**
Description: Closes the dialog and moves focus to trigger or the defined final focus element


# Editable 



## Anatomy



```tsx
<Editable.Root>
  <Editable.Label />
  <Editable.Area>
    <Editable.Input />
    <Editable.Preview />
  </Editable.Area>
  <Editable.Control>
    <Editable.EditTrigger />
    <Editable.SubmitTrigger />
    <Editable.CancelTrigger />
  </Editable.Control>
</Editable.Root>
```

## Examples

**Example: basic**

```ripple
import { Editable } from 'ark-ripple/editable';
import { Pencil } from 'lucide-ripple';
import styles from 'styles/editable.module.css';

export component Basic() {
  <Editable.Root class={styles.Root} placeholder="Enter text..." defaultValue="Hello World">
    <Editable.Label class={styles.Label}>{'Label'}</Editable.Label>
    <Editable.Area class={styles.Area}>
      <Editable.Input class={styles.Input} />
      <Editable.Preview class={styles.Preview} />
    </Editable.Area>
    <Editable.Control class={styles.Control}>
      <Editable.EditTrigger class={styles.EditTrigger}>
        <Pencil />
      </Editable.EditTrigger>
    </Editable.Control>
  </Editable.Root>
}

```

### Controlled

Use the `value` and `onValueChange` props to control the editable state.

**Example: controlled**

```ripple
import { Editable } from 'ark-ripple/editable';
import { Pencil } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/editable.module.css';

export component Controlled() {
  let value = track('Hello World');

  <Editable.Root
    class={styles.Root}
    placeholder="Enter text..."
    {value}
    onValueChange={(e) => {
      @value = e.value;
    }}
  >
    <Editable.Label class={styles.Label}>{'Label'}</Editable.Label>
    <Editable.Area class={styles.Area}>
      <Editable.Input class={styles.Input} />
      <Editable.Preview class={styles.Preview} />
    </Editable.Area>
    <Editable.Control class={styles.Control}>
      <Editable.EditTrigger class={styles.EditTrigger}>
        <Pencil />
      </Editable.EditTrigger>
    </Editable.Control>
  </Editable.Root>
}

```

### Root Provider

An alternative way to control the editable is to use the `RootProvider` component and the `useEditable` hook. This way
you can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { Editable, useEditable } from 'ark-ripple/editable';
import { Pencil } from 'lucide-ripple';
import styles from 'styles/editable.module.css';

export component RootProvider() {
  const editable = useEditable({ defaultValue: 'Hello World' });

  <Editable.RootProvider class={styles.Root} value={editable}>
    <Editable.Label class={styles.Label}>{'Label'}</Editable.Label>
    <Editable.Area class={styles.Area}>
      <Editable.Input class={styles.Input} />
      <Editable.Preview class={styles.Preview} />
    </Editable.Area>
    <Editable.Control class={styles.Control}>
      <Editable.EditTrigger class={styles.EditTrigger}>
        <Pencil />
      </Editable.EditTrigger>
    </Editable.Control>
  </Editable.RootProvider>
}

```

### Context

Access the editable's state with `Editable.Context` or the `useEditableContext` hook—great for showing keyboard hints
when editing.

**Example: context**

```ripple
import { Editable } from 'ark-ripple/editable';
import { Pencil } from 'lucide-ripple';
import styles from 'styles/editable.module.css';

export component Context() {
  <Editable.Root class={styles.Root} placeholder="Enter text..." defaultValue="Hello World">
    <Editable.Label class={styles.Label}>{'Label'}</Editable.Label>
    <Editable.Area class={styles.Area}>
      <Editable.Input class={styles.Input} />
      <Editable.Preview class={styles.Preview} />
    </Editable.Area>
    <Editable.Context>
      component children({ context }) {
        if (@context.editing) {
          <span class={styles.HelperText}>{'Enter to save, Esc to cancel'}</span>
        } else {
          <Editable.Control class={styles.Control}>
            <Editable.EditTrigger class={styles.EditTrigger}>
              <Pencil />
            </Editable.EditTrigger>
          </Editable.Control>
        }
      }
    </Editable.Context>
  </Editable.Root>
}

```

### 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.

**Example: controls**

```ripple
import { Editable } from 'ark-ripple/editable';
import { Check, Pencil, X } from 'lucide-ripple';
import styles from 'styles/editable.module.css';

export component Controls() {
  <Editable.Root class={styles.Root} defaultValue="Click edit to start">
    <Editable.Label class={styles.Label}>{'Label'}</Editable.Label>
    <Editable.Area class={styles.Area}>
      <Editable.Input class={styles.Input} />
      <Editable.Preview class={styles.Preview} />
    </Editable.Area>
    <Editable.Context>
      component children({ context }) {
        <Editable.Control class={styles.Control}>
          if (@context.editing) {
            <Editable.SubmitTrigger class={styles.SubmitTrigger}>
              <Check />
            </Editable.SubmitTrigger>
            <Editable.CancelTrigger class={styles.CancelTrigger}>
              <X />
            </Editable.CancelTrigger>
          } else {
            <Editable.EditTrigger class={styles.EditTrigger}>
              <Pencil />
            </Editable.EditTrigger>
          }
        </Editable.Control>
      }
    </Editable.Context>
  </Editable.Root>
}

```

### Textarea

Use the `asChild` prop on `Editable.Input` to render a textarea for multi-line editing.

**Example: textarea**

```ripple
import { Editable } from 'ark-ripple/editable';
import styles from 'styles/editable.module.css';

export component WithTextarea() {
  <Editable.Root
    class={styles.Root}
    placeholder="Enter a description..."
    defaultValue="Ark UI is a headless component library for building reusable, scalable design systems."
    activationMode="dblclick"
  >
    <Editable.Label class={styles.Label}>{'Description'}</Editable.Label>
    <Editable.Area class={styles.Area}>
      <Editable.Input class={styles.Input}>
        component asChild({ propsFn }) {
          <textarea {...propsFn()} />
        }
      </Editable.Input>
      <Editable.Preview class={styles.Preview} />
    </Editable.Area>
    <div class={styles.HelperText}>{'Press Cmd + Enter to save'}</div>
  </Editable.Root>
}

```

### Field

The `Field` component helps manage form-related state and accessibility attributes of an editable. It includes handling
ARIA labels, helper text, and error text to ensure proper accessibility.

**Example: with-field**

```ripple
import { Editable } from 'ark-ripple/editable';
import { Field } from 'ark-ripple/field';
import field from 'styles/field.module.css';
import styles from 'styles/editable.module.css';

export component WithField() {
  <Field.Root class={field.Root}>
    <Editable.Root class={styles.Root} placeholder="Enter your bio">
      <Editable.Label class={field.Label}>{'Bio'}</Editable.Label>
      <Editable.Area class={styles.Area}>
        <Editable.Input class={styles.Input} />
        <Editable.Preview class={styles.Preview} />
      </Editable.Area>
    </Editable.Root>
    <Field.HelperText class={field.HelperText}>{'Click to edit your bio'}</Field.HelperText>
    <Field.ErrorText class={field.ErrorText}>{'Bio is required'}</Field.ErrorText>
  </Field.Root>
}

```

## Guides

### Auto-resizing

To auto-grow the editable as the content changes, set the `autoResize` prop to `true`.

```tsx
<Editable.Root placeholder="Placeholder" autoResize>
  {/*...*/}
</Editable.Root>
```

### Max Length

Use the `maxLength` prop to set a maximum number of characters that can be entered into the editable.

```tsx
<Editable.Root placeholder="Placeholder" autoResize maxLength={10}>
  {/*...*/}
</Editable.Root>
```

### 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
<Editable.Root placeholder="Placeholder" activationMode="dblclick">
  {/*...*/}
</Editable.Root>
```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `activationMode` | `ActivationMode` | No | The activation mode for the preview element.

- "focus" - Enter edit mode when the preview is focused
- "dblclick" - Enter edit mode when the preview is double-clicked
- "click" - Enter edit mode when the preview is clicked
- "none" - Edit can be triggered programmatically only |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `autoResize` | `boolean` | No | Whether the editable should auto-resize to fit the content. |
| `defaultEdit` | `boolean` | No | Whether the editable is in edit mode by default. |
| `defaultValue` | `string` | No | The initial value of the editable when rendered.
Use when you don't need to control the value of the editable. |
| `disabled` | `boolean` | No | Whether the editable is disabled. |
| `edit` | `boolean` | No | Whether the editable is in edit mode. |
| `finalFocusEl` | `() => HTMLElement | null` | No | The element to receive focus when the editable is closed. |
| `form` | `string` | No | The associate form of the underlying input. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{
  root: string
  area: string
  label: string
  preview: string
  input: string
  control: string
  submitTrigger: string
  cancelTrigger: string
  editTrigger: string
}>` | No | The ids of the elements in the editable. Useful for composition. |
| `invalid` | `boolean` | No | Whether the input's value is invalid. |
| `maxLength` | `number` | No | The maximum number of characters allowed in the editable |
| `name` | `string` | No | The name attribute of the editable component. Used for form submission. |
| `onEditChange` | `(details: EditChangeDetails) => void` | No | Function to call when the edit mode changes. |
| `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component |
| `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component |
| `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | Function to call when the value changes. |
| `onValueCommit` | `(details: ValueChangeDetails) => void` | No | Function to call when the value is committed. |
| `onValueRevert` | `(details: ValueChangeDetails) => void` | No | Function to call when the value is reverted. |
| `placeholder` | `string | { edit: string; preview: string }` | No | The placeholder text for the editable. |
| `readOnly` | `boolean` | No | Whether the editable is read-only. |
| `required` | `boolean` | No | Whether the editable is required. |
| `selectOnFocus` | `boolean` | No | Whether to select the text in the input when it is focused. |
| `submitMode` | `SubmitMode` | No | The action that triggers submit in the edit mode:

- "enter" - Trigger submit when the enter key is pressed
- "blur" - Trigger submit when the editable is blurred
- "none" - No action will trigger submit. You need to use the submit button
- "both" - Pressing `Enter` and blurring the input will trigger submit |
| `translations` | `IntlTranslations` | No | The translations for the editable. |
| `value` | `string` | No | The controlled value of the editable. |


**Area Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Area Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | editable |
| `[data-part]` | area |
| `[data-focus]` | Present when focused |
| `[data-disabled]` | Present when disabled |
| `[data-placeholder-shown]` | Present when placeholder is shown |


**CancelTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**EditTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Input Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Input Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | editable |
| `[data-part]` | input |
| `[data-disabled]` | Present when disabled |
| `[data-readonly]` | Present when read-only |
| `[data-invalid]` | Present when invalid |
| `[data-autoresize]` |  |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | editable |
| `[data-part]` | label |
| `[data-focus]` | Present when focused |
| `[data-invalid]` | Present when invalid |
| `[data-required]` | Present when required |


**Preview Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Preview Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | editable |
| `[data-part]` | preview |
| `[data-placeholder-shown]` | Present when placeholder is shown |
| `[data-readonly]` | Present when read-only |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]` | Present when invalid |
| `[data-autoresize]` |  |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseEditableReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**SubmitTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `editing` | `boolean` | Whether the editable is in edit mode |
| `empty` | `boolean` | Whether the editable value is empty |
| `value` | `string` | The current value of the editable |
| `valueText` | `string` | The current value of the editable, or the placeholder if the value is empty |
| `setValue` | `(value: string) => void` | Function to set the value of the editable |
| `clearValue` | `VoidFunction` | Function to clear the value of the editable |
| `edit` | `VoidFunction` | Function to enter edit mode |
| `cancel` | `VoidFunction` | Function to exit edit mode, and discard any changes |
| `submit` | `VoidFunction` | Function to exit edit mode, and submit any changes |


## Accessibility

### Keyboard Support

**`Enter`**
Description: Saves the edited content and exits edit mode.

**`Escape`**
Description: Discards the changes and exits edit mode.


# Field 



## Anatomy



```tsx
<Field.Root>
  <Field.Label />
  <Field.Input />
  <Field.Textarea />
  <Field.Select />
  <Field.HelperText />
  <Field.ErrorText />
</Field.Root>
```

## Examples

The `Field` component provides contexts such as `invalid`, `disabled`, `required`, and `readOnly` for form elements.
While most Ark UI components natively support these contexts, you can also use the `Field` component with standard HTML
form elements.

### Input

This example shows how to use the `Field` component with a standard input field.

**Example: input**

```ripple
import { Field } from 'ark-ripple/field';
import styles from 'styles/field.module.css';

export component Input() {
  <Field.Root class={styles.Root}>
    <Field.Label class={styles.Label}>{'Label'}</Field.Label>
    <Field.Input class={styles.Input} />
    <Field.HelperText class={styles.HelperText}>{'Some additional Info'}</Field.HelperText>
    <Field.ErrorText class={styles.ErrorText}>{'Error Info'}</Field.ErrorText>
  </Field.Root>
}

```

### Textarea

This example illustrates how to use the `Field` component with a textarea element.

**Example: textarea**

```ripple
import { Field } from 'ark-ripple/field';
import styles from 'styles/field.module.css';

export component Textarea() {
  <Field.Root class={styles.Root}>
    <Field.Label class={styles.Label}>{'Label'}</Field.Label>
    <Field.Textarea class={styles.Textarea} />
    <Field.HelperText class={styles.HelperText}>{'Some additional Info'}</Field.HelperText>
    <Field.ErrorText class={styles.ErrorText}>{'Error Info'}</Field.ErrorText>
  </Field.Root>
}

```

### Textarea Autoresize

Pass the `autoresize` prop to the `Textarea` component to enable automatic resizing as the user types.

**Example: textarea-autoresize**

```ripple
import { Field } from 'ark-ripple/field';
import styles from 'styles/field.module.css';

export component TextareaAutoresize() {
  <Field.Root class={styles.Root}>
    <Field.Label class={styles.Label}>{'Label'}</Field.Label>
    <Field.Textarea class={styles.Textarea} autoresize />
    <Field.HelperText class={styles.HelperText}>{'Some additional Info'}</Field.HelperText>
    <Field.ErrorText class={styles.ErrorText}>{'Error Info'}</Field.ErrorText>
  </Field.Root>
}

```

### Select

This example demonstrates how to integrate the `Field` component with a select dropdown.

**Example: select**

```ripple
import { Field } from 'ark-ripple/field';
import styles from 'styles/field.module.css';

export component Select() {
  <Field.Root class={styles.Root}>
    <Field.Label class={styles.Label}>{'Label'}</Field.Label>
    <Field.Select class={styles.Select}>
      <option value="1">{'Option 1'}</option>
      <option value="2">{'Option 2'}</option>
      <option value="3">{'Option 3'}</option>
    </Field.Select>
    <Field.HelperText class={styles.HelperText}>{'Some additional Info'}</Field.HelperText>
    <Field.ErrorText class={styles.ErrorText}>{'Error Info'}</Field.ErrorText>
  </Field.Root>
}

```

### Checkbox

This example demonstrates how to integrate the `Field` and `Checkbox` components.

```ripple
import { Checkbox } from 'ark-ripple/checkbox';
import { Field } from 'ark-ripple/field';
import { Check, Minus } from 'lucide-ripple';
import styles from 'styles/checkbox.module.css';
import field from 'styles/field.module.css';

export component WithField() {
  <Field.Root class={field.Root} data-inline>
    <Checkbox.Root class={styles.Root}>
      <Checkbox.Control class={styles.Control}>
        <Checkbox.Indicator class={styles.Indicator}>
          <Check />
        </Checkbox.Indicator>
        <Checkbox.Indicator class={styles.Indicator} indeterminate>
          <Minus />
        </Checkbox.Indicator>
      </Checkbox.Control>
      <Checkbox.Label class={styles.Label}>{'Label'}</Checkbox.Label>
      <Checkbox.HiddenInput />
    </Checkbox.Root>
    <Field.HelperText class={field.HelperText}>{'Additional Info'}</Field.HelperText>
    <Field.ErrorText class={field.ErrorText}>{'Error Info'}</Field.ErrorText>
  </Field.Root>
}
```

### Root Provider

An alternative way to control the field is to use the `RootProvider` component and the `useField` hook. This way you can
access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { Field } from 'ark-ripple/field';
import { useField } from 'ark-ripple/field';
import styles from 'styles/field.module.css';
import button from 'styles/button.module.css';
import { track } from 'ripple';

export component RootProvider() {
  let invalid = track(false);
  const field = useField({ id: 'field', invalid });

  <div class="vstack">
    <button
      class={button.Root}
      style={{ marginBottom: '1rem' }}
      onClick={() => {
        @invalid = !@invalid;
      }}
    >
      {'Toggle Invalid'}
    </button>
    <Field.RootProvider class={styles.Root} value={field}>
      <Field.Label class={styles.Label}>{'Label'}</Field.Label>
      <Field.Input class={styles.Input} />
      <Field.HelperText class={styles.HelperText}>{'Some additional Info'}</Field.HelperText>
      <Field.ErrorText class={styles.ErrorText}>{'Error Info'}</Field.ErrorText>
    </Field.RootProvider>
  </div>
}

```

### Custom Control

Use the `Field.Context` or `useFieldContext` hook to access the internal state of the field.This can help you wire up
custom controls with the `Field` component.

**Example: custom-control**

```ripple
import { Field } from 'ark-ripple/field';
import styles from 'styles/field.module.css';

export component CustomControl() {
  <Field.Root class={styles.Root} invalid>
    <Field.Label class={styles.Label}>{'Any Control'}</Field.Label>
    <Field.Context>
      component children({ context }) {
        <input class={styles.Input} {...@context.getInputProps()} />
      }
    </Field.Context>
    <Field.HelperText class={styles.HelperText}>
      {'Uses getInputProps() for maximum flexibility'}
    </Field.HelperText>
    <Field.ErrorText class={styles.ErrorText}>{'This field has an error'}</Field.ErrorText>
  </Field.Root>
}

```

## API Reference

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `disabled` | `boolean` | No | Indicates whether the field is disabled. |
| `ids` | `ElementIds` | No | The ids of the field parts. |
| `invalid` | `boolean` | No | Indicates whether the field is invalid. |
| `readOnly` | `boolean` | No | Indicates whether the field is read-only. |
| `required` | `boolean` | No | Indicates whether the field is required. |
| `target` | `string` | No | The target field item value the label should point to. |


**ErrorText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**HelperText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Input Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**RequiredIndicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `fallback` | `string | number | bigint | boolean | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...>` | No |  |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `{ ariaDescribedby: string | undefined; ids: { root: string; control: string; label: string; errorText: string; helperText: string; }; refs: { rootRef: RefObject<HTMLDivElement | null>; }; ... 11 more ...; getRequiredIndicatorProps: () => Omit<...>; }` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Select Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Textarea Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `autoresize` | `boolean` | No | Whether the textarea should autoresize |



# Fieldset 

## Anatomy



```tsx
<Fieldset.Root>
  <Fieldset.Legend />
  <Fieldset.HelperText />
  <Fieldset.ErrorText />
</Fieldset.Root>
```

## 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

**Example: basic**

```ripple
import { Field } from 'ark-ripple/field';
import { Fieldset } from 'ark-ripple/fieldset';
import field from 'styles/field.module.css';
import styles from 'styles/fieldset.module.css';

export component Basic() {
  <Fieldset.Root class={styles.Root}>
    <Fieldset.Legend class={styles.Legend}>{'Contact Details'}</Fieldset.Legend>

    <Field.Root class={field.Root}>
      <Field.Label class={field.Label}>{'Name'}</Field.Label>
      <Field.Input class={field.Input} placeholder="John Doe" />
    </Field.Root>

    <Field.Root class={field.Root}>
      <Field.Label class={field.Label}>{'Email'}</Field.Label>
      <Field.Input class={field.Input} type="email" placeholder="john@example.com" />
    </Field.Root>
  </Fieldset.Root>
}

```

### Field

This example demonstrates how to use the `Field` component with a standard input field within a `Fieldset`.

**Example: with-field**

```ripple
import { Field } from 'ark-ripple/field';
import { Fieldset } from 'ark-ripple/fieldset';
import field from 'styles/field.module.css';
import styles from 'styles/fieldset.module.css';

export component WithField() {
  <Fieldset.Root class={styles.Root}>
    <Fieldset.Legend class={styles.Legend}>{'Personal Information'}</Fieldset.Legend>

    <Field.Root class={field.Root}>
      <Field.Label class={field.Label}>{'First Name'}</Field.Label>
      <Field.Input class={field.Input} placeholder="Enter your first name" />
      <Field.HelperText class={field.HelperText}>{'As it appears on your ID'}</Field.HelperText>
    </Field.Root>

    <Field.Root class={field.Root}>
      <Field.Label class={field.Label}>{'Last Name'}</Field.Label>
      <Field.Input class={field.Input} placeholder="Enter your last name" />
    </Field.Root>
  </Fieldset.Root>
}

```

### Checkbox

This example shows how to use the `Fieldset` component with other Ark UI form elements like `Checkbox`.

**Example: with-checkbox**

```ripple
import { Checkbox } from 'ark-ripple/checkbox';
import { Fieldset } from 'ark-ripple/fieldset';
import { Check } from 'lucide-ripple';
import checkbox from 'styles/checkbox.module.css';
import styles from 'styles/fieldset.module.css';

export component WithCheckbox() {
  <Fieldset.Root class={styles.Root}>
    <Fieldset.Legend class={styles.Legend}>{'Email Preferences'}</Fieldset.Legend>

    <Checkbox.Root class={checkbox.Root} defaultChecked>
      <Checkbox.Control class={checkbox.Control}>
        <Checkbox.Indicator class={checkbox.Indicator}>
          <Check />
        </Checkbox.Indicator>
      </Checkbox.Control>
      <Checkbox.Label class={checkbox.Label}>{'Product updates'}</Checkbox.Label>
      <Checkbox.HiddenInput />
    </Checkbox.Root>

    <Checkbox.Root class={checkbox.Root}>
      <Checkbox.Control class={checkbox.Control}>
        <Checkbox.Indicator class={checkbox.Indicator}>
          <Check />
        </Checkbox.Indicator>
      </Checkbox.Control>
      <Checkbox.Label class={checkbox.Label}>{'Marketing emails'}</Checkbox.Label>
      <Checkbox.HiddenInput />
    </Checkbox.Root>
  </Fieldset.Root>
}

```

### Root Provider

An alternative way to control the fieldset is to use the `RootProvider` component and the `useFieldset` hook. This way
you can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { Field } from 'ark-ripple/field';
import { Fieldset, useFieldset } from 'ark-ripple/fieldset';
import field from 'styles/field.module.css';
import styles from 'styles/fieldset.module.css';

export component RootProvider() {
  const fieldset = useFieldset();

  <Fieldset.RootProvider class={styles.Root} value={fieldset}>
    <Fieldset.Legend class={styles.Legend}>{'Contact Details'}</Fieldset.Legend>

    <Field.Root class={field.Root}>
      <Field.Label class={field.Label}>{'Name'}</Field.Label>
      <Field.Input class={field.Input} placeholder="John Doe" />
    </Field.Root>

    <Field.Root class={field.Root}>
      <Field.Label class={field.Label}>{'Email'}</Field.Label>
      <Field.Input class={field.Input} type="email" placeholder="john@example.com" />
    </Field.Root>
  </Fieldset.RootProvider>
}

```

### Input with Select

This example shows how to use the `Fieldset` component with `Field.Input` and `Select` to create a interactive phone
input component.

**Example: phone-input**

```ripple
import { Fieldset } from 'ark-ripple/fieldset';
import { Field } from 'ark-ripple/field';
import { track } from 'ripple';
import { Portal } from 'ark-ripple/portal';
import { Select, createListCollection } from 'ark-ripple/select';
import { ChevronsUpDown } from 'lucide-ripple';
import styles from 'styles/fieldset.module.css';
import field from 'styles/field.module.css';
import select from 'styles/select.module.css';

const extensions = createListCollection(
  {
    items: [
      { label: '+1', value: '+1' },
      { label: '+44', value: '+44' },
      { label: '+49', value: '+49' },
      { label: '+41', value: '+41' },
    ],
  },
);

export component PhoneInput() {
  let inputRef = track<HTMLInputElement | null>(null);

  const focusInput = () => {
    setTimeout(() => {
      @inputRef?.focus();
    });
  };

  <Fieldset.Root class={styles.Root}>
    <Fieldset.Legend class={styles.Legend} onClick={focusInput}>{'Mobile Number'}</Fieldset.Legend>

    <div style={{ display: 'flex', alignItems: 'flex-start', gap: '0.5rem' }}>
      <Field.Root>
        <Select.Root
          class={select.Root}
          collection={extensions}
          defaultValue={['+1']}
          onValueChange={focusInput}
        >
          <Select.Control class={select.Control}>
            <Select.Trigger class={select.Trigger}>
              <Select.ValueText placeholder="Select" />
              <ChevronsUpDown />
            </Select.Trigger>
          </Select.Control>
          <Portal>
            <Select.Positioner>
              <Select.Content class={select.Content}>
                for (const item of extensions.items; key item.value) {
                  <Select.Item class={select.Item} {item}>
                    <Select.ItemText class={select.ItemText}>{item.label}</Select.ItemText>
                  </Select.Item>
                }
              </Select.Content>
            </Select.Positioner>
          </Portal>
          <Select.HiddenSelect />
        </Select.Root>
      </Field.Root>

      <Field.Root class={field.Root}>
        <Field.Input
          class={field.Input}
          {ref (el: HTMLInputElement) => {
            @inputRef = el;
            return () => {
              @inputRef = null;
            };
          }}
        />
      </Field.Root>
    </div>
  </Fieldset.Root>
}

```

## API Reference

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `invalid` | `boolean` | No | Indicates whether the fieldset is invalid. |


**ErrorText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**HelperText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Legend Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `{ refs: { rootRef: RefObject<HTMLFieldSetElement | null>; }; ids: { legend: string; errorText: string; helperText: string; }; disabled: boolean; invalid: boolean; getRootProps: () => Omit<...>; getLegendProps: () => Omit<...>; getHelperTextProps: () => Omit<...>; getErrorTextProps: () => Omit<...>; }` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |



# File Upload 



## Anatomy



```tsx
<FileUpload.Root>
  <FileUpload.Label />
  <FileUpload.Dropzone>
    <FileUpload.Trigger />
  </FileUpload.Dropzone>
  <FileUpload.ItemGroup>
    <FileUpload.Item>
      <FileUpload.ItemPreview>
        <FileUpload.ItemPreviewImage />
      </FileUpload.ItemPreview>
      <FileUpload.ItemName />
      <FileUpload.ItemSizeText />
      <FileUpload.ItemDeleteTrigger />
    </FileUpload.Item>
  </FileUpload.ItemGroup>
  <FileUpload.ClearTrigger />
  <FileUpload.HiddenInput />
</FileUpload.Root>
```

## Examples

**Example: basic**

```ripple
import { FileUpload } from 'ark-ripple/file-upload';
import { Paperclip, X } from 'lucide-ripple';
import styles from 'styles/file-upload.module.css';

export component Basic() {
  <FileUpload.Root maxFiles={5} class={styles.Root}>
    <FileUpload.Label class={styles.Label}>{'File Upload'}</FileUpload.Label>
    <FileUpload.Trigger class={styles.Trigger}>
      <Paperclip />
      {' Choose file(s)'}
    </FileUpload.Trigger>
    <FileUpload.ItemGroup class={styles.ItemGroup}>
      <FileUpload.Context>
        component children({ context }) {
          for (const file of @context.acceptedFiles; key file.name) {
            <FileUpload.Item {file} class={styles.ItemCompact}>
              <FileUpload.ItemName class={styles.ItemName} />
              <FileUpload.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                <X />
              </FileUpload.ItemDeleteTrigger>
            </FileUpload.Item>
          }
        }
      </FileUpload.Context>
    </FileUpload.ItemGroup>
    <FileUpload.HiddenInput />
  </FileUpload.Root>
}

```

### Initial Files

Use the `defaultAcceptedFiles` prop to set the initial files in the file upload component.

**Example: initial-files**

```ripple
import { FileUpload } from 'ark-ripple/file-upload';
import { File as FileIcon, Paperclip, X } from 'lucide-ripple';
import styles from 'styles/file-upload.module.css';

export component InitialFiles() {
  <FileUpload.Root
    defaultAcceptedFiles={[
      new File(['Welcome to Ark UI Ripple'], 'README.md', { type: 'text/plain' }),
    ]}
    class={styles.Root}
  >
    <FileUpload.Label class={styles.Label}>{'File Upload'}</FileUpload.Label>
    <FileUpload.Trigger class={styles.Trigger}>
      <Paperclip />
      {' Choose file(s)'}
    </FileUpload.Trigger>
    <FileUpload.ItemGroup class={styles.ItemGroup}>
      <FileUpload.Context>
        component children({ context }) {
          for (const file of @context.acceptedFiles; key file.name) {
            <FileUpload.Item {file} class={styles.Item}>
              <div class={styles.ItemPreview}>
                <FileIcon />
              </div>
              <FileUpload.ItemName class={styles.ItemName} />
              <FileUpload.ItemSizeText class={styles.ItemSizeText} />
              <FileUpload.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                <X />
              </FileUpload.ItemDeleteTrigger>
            </FileUpload.Item>
          }
        }
      </FileUpload.Context>
    </FileUpload.ItemGroup>
    <FileUpload.HiddenInput />
  </FileUpload.Root>
}

```

### Clear Trigger

Use the `ClearTrigger` to remove all uploaded files at once.

**Example: clear-trigger**

```ripple
import { FileUpload } from 'ark-ripple/file-upload';
import { Paperclip, X } from 'lucide-ripple';
import styles from 'styles/file-upload.module.css';

export component ClearTrigger() {
  <FileUpload.Root maxFiles={5} accept="image/png,image/jpeg" class={styles.Root}>
    <FileUpload.Label class={styles.Label}>{'File Upload'}</FileUpload.Label>
    <div class={styles.Actions}>
      <FileUpload.Trigger class={styles.Trigger}>
        <Paperclip />
        {' Choose file(s)'}
      </FileUpload.Trigger>
      <FileUpload.ClearTrigger class={styles.ClearTrigger}>{'Clear Files'}</FileUpload.ClearTrigger>
    </div>
    <FileUpload.ItemGroup class={styles.ItemGroup}>
      <FileUpload.Context>
        component children({ context }) {
          for (const file of @context.acceptedFiles; key file.name) {
            <FileUpload.Item {file} class={styles.Item}>
              <FileUpload.ItemPreview type="image/*" class={styles.ItemPreview}>
                <FileUpload.ItemPreviewImage class={styles.ItemPreviewImage} />
              </FileUpload.ItemPreview>
              <FileUpload.ItemName class={styles.ItemName} />
              <FileUpload.ItemSizeText class={styles.ItemSizeText} />
              <FileUpload.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                <X />
              </FileUpload.ItemDeleteTrigger>
            </FileUpload.Item>
          }
        }
      </FileUpload.Context>
    </FileUpload.ItemGroup>
    <FileUpload.HiddenInput />
  </FileUpload.Root>
}

```

### Dropzone

Use the `Dropzone` to enable drag-and-drop. It exposes a `data-dragging` attribute for styling.

**Example: dropzone**

```ripple
import { FileUpload } from 'ark-ripple/file-upload';
import { File, Upload, X } from 'lucide-ripple';
import styles from 'styles/file-upload.module.css';

export component Dropzone() {
  <FileUpload.Root maxFiles={5} class={styles.Root}>
    <FileUpload.Label class={styles.Label}>{'File Upload'}</FileUpload.Label>
    <FileUpload.Dropzone class={styles.Dropzone}>
      <Upload class={styles.DropzoneIcon} />
      <div class={styles.DropzoneContent}>
        <span class={styles.DropzoneTitle}>{'Drag and drop files here'}</span>
        <span class={styles.DropzoneDescription}>{'or click to browse'}</span>
      </div>
    </FileUpload.Dropzone>
    <FileUpload.ItemGroup class={styles.ItemGroup}>
      <FileUpload.Context>
        component children({ context }) {
          for (const file of @context.acceptedFiles; key file.name) {
            <FileUpload.Item {file} class={styles.Item}>
              <FileUpload.ItemPreview type="image/*" class={styles.ItemPreview}>
                <FileUpload.ItemPreviewImage class={styles.ItemPreviewImage} />
              </FileUpload.ItemPreview>
              <FileUpload.ItemPreview type=".*" class={styles.ItemPreview}>
                <File />
              </FileUpload.ItemPreview>
              <FileUpload.ItemName class={styles.ItemName} />
              <FileUpload.ItemSizeText class={styles.ItemSizeText} />
              <FileUpload.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                <X />
              </FileUpload.ItemDeleteTrigger>
            </FileUpload.Item>
          }
        }
      </FileUpload.Context>
    </FileUpload.ItemGroup>
    <FileUpload.HiddenInput />
  </FileUpload.Root>
}

```

### Directory Upload

Use the `directory` prop to upload entire folders. Access file paths through `file.webkitRelativePath`.

**Example: directory-upload**

```ripple
import { FileUpload } from 'ark-ripple/file-upload';
import { File, Folder, X } from 'lucide-ripple';
import styles from 'styles/file-upload.module.css';

export component DirectoryUpload() {
  <FileUpload.Root directory class={styles.Root}>
    <FileUpload.Label class={styles.Label}>{'Upload Folder'}</FileUpload.Label>
    <FileUpload.Trigger class={styles.Trigger}>
      <Folder style={{ width: '1rem', height: '1rem' }} />
      {' Select Folder'}
    </FileUpload.Trigger>
    <FileUpload.ItemGroup class={styles.ItemGroup}>
      <FileUpload.Context>
        component children({ context }) {
          for (const file of @context.acceptedFiles; key file.name) {
            <FileUpload.Item {file} class={styles.Item}>
              <div class={styles.ItemPreview}>
                <File />
              </div>
              <FileUpload.ItemName class={styles.ItemName}>
                {file.webkitRelativePath || file.name}
              </FileUpload.ItemName>
              <FileUpload.ItemSizeText class={styles.ItemSizeText} />
              <FileUpload.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                <X />
              </FileUpload.ItemDeleteTrigger>
            </FileUpload.Item>
          }
        }
      </FileUpload.Context>
    </FileUpload.ItemGroup>
    <FileUpload.HiddenInput />
  </FileUpload.Root>
}

```

> When uploading directories with many files, set `maxFiles` to a higher value or remove it entirely to prevent
> rejections.

### Accepted File Types

Use the `accept` prop to restrict file types. Accepts MIME types (`image/png`) or extensions (`.pdf`).

**Example: accepted-file-types**

```ripple
import { FileUpload } from 'ark-ripple/file-upload';
import { CircleAlert, Image, Upload, X } from 'lucide-ripple';
import styles from 'styles/file-upload.module.css';

export component AcceptedFileTypes() {
  <FileUpload.Root accept="image/png,image/jpeg" class={styles.Root}>
    <FileUpload.Label class={styles.Label}>{'Upload Images (PNG and JPEG only)'}</FileUpload.Label>
    <FileUpload.Dropzone class={styles.Dropzone}>
      <Upload class={styles.DropzoneIcon} />
      <div class={styles.DropzoneContent}>
        <span class={styles.DropzoneTitle}>{'Drop your images here'}</span>
        <span class={styles.DropzoneDescription}>{'Only PNG and JPEG files'}</span>
      </div>
    </FileUpload.Dropzone>

    <FileUpload.Context>
      component children({ context }) {
        if (@context.acceptedFiles.length > 0) {
          <FileUpload.ItemGroup class={styles.ItemGroup}>
            for (const file of @context.acceptedFiles; key file.name) {
              <FileUpload.Item {file} class={styles.Item}>
                <FileUpload.ItemPreview type="image/*" class={styles.ItemPreview}>
                  <FileUpload.ItemPreviewImage class={styles.ItemPreviewImage} />
                </FileUpload.ItemPreview>
                <FileUpload.ItemPreview type=".*" class={styles.ItemPreview}>
                  <Image />
                </FileUpload.ItemPreview>
                <FileUpload.ItemName class={styles.ItemName} />
                <FileUpload.ItemSizeText class={styles.ItemSizeText} />
                <FileUpload.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                  <X />
                </FileUpload.ItemDeleteTrigger>
              </FileUpload.Item>
            }
          </FileUpload.ItemGroup>
        }

        if (@context.rejectedFiles.length > 0) {
          <FileUpload.ItemGroup class={styles.ItemGroup}>
            for (const fileRejection of @context.rejectedFiles; key fileRejection.file.name) {
              <FileUpload.Item file={fileRejection.file} class={styles.Item} data-rejected>
                <div class={styles.ItemPreview}>
                  <CircleAlert />
                </div>
                <FileUpload.ItemName class={styles.ItemName} />
                <FileUpload.ItemSizeText class={styles.ItemSizeText} />
                <div class={styles.ErrorList}>
                  for (const error of fileRejection.errors; key error) {
                    <div class={styles.ErrorItem}>{error}</div>
                  }
                </div>
              </FileUpload.Item>
            }
          </FileUpload.ItemGroup>
        }
      }
    </FileUpload.Context>

    <FileUpload.HiddenInput />
  </FileUpload.Root>
}

```

### Error Handling

Set constraints with `maxFiles`, `maxFileSize`, `minFileSize`, and `accept`. Rejected files include error codes like
`TOO_MANY_FILES`, `FILE_INVALID_TYPE`, `FILE_TOO_LARGE`, or `FILE_EXISTS`.

**Example: error-handling**

```ripple
import { FileUpload } from 'ark-ripple/file-upload';
import type { FileUploadFileError } from 'ark-ripple/file-upload';
import { CircleAlert, CircleCheck, File, Upload, X } from 'lucide-ripple';
import styles from 'styles/file-upload.module.css';

const errorMessages: Record<FileUploadFileError, string> = {
  TOO_MANY_FILES: 'Too many files selected (max 3 allowed)',
  FILE_INVALID_TYPE: 'Invalid file type (only images and PDFs allowed)',
  FILE_TOO_LARGE: 'File too large (max 1MB)',
  FILE_TOO_SMALL: 'File too small (min 1KB)',
  FILE_INVALID: 'Invalid file',
  FILE_EXISTS: 'File already exists',
};

export component ErrorHandling() {
  <FileUpload.Root
    maxFiles={3}
    maxFileSize={1024 * 1024}
    minFileSize={1024}
    accept="image/*,application/pdf"
    class={styles.Root}
  >
    <FileUpload.Label class={styles.Label}>{'Upload Documents'}</FileUpload.Label>
    <FileUpload.Dropzone class={styles.Dropzone}>
      <Upload class={styles.DropzoneIcon} />
      <div class={styles.DropzoneContent}>
        <span class={styles.DropzoneTitle}>{'Drop files here'}</span>
        <span class={styles.DropzoneDescription}>{'Images and PDFs, max 1MB each'}</span>
      </div>
    </FileUpload.Dropzone>

    <FileUpload.Context>
      component children({ context }) {
        if (@context.acceptedFiles.length > 0) {
          <div class={styles.Section}>
            <div class={styles.SectionTitle} data-status="accepted">
              <CircleCheck
                style={{
                  width: '0.875rem',
                  height: '0.875rem',
                  display: 'inline',
                  marginRight: '0.25rem',
                  verticalAlign: 'middle',
                }}
              />
              {'Accepted Files'}
            </div>
            <FileUpload.ItemGroup class={styles.ItemGroup}>
              for (const file of @context.acceptedFiles; key file.name) {
                <FileUpload.Item {file} class={styles.Item}>
                  <FileUpload.ItemPreview type="image/*" class={styles.ItemPreview}>
                    <FileUpload.ItemPreviewImage class={styles.ItemPreviewImage} />
                  </FileUpload.ItemPreview>
                  <FileUpload.ItemPreview type="application/pdf" class={styles.ItemPreview}>
                    <File />
                  </FileUpload.ItemPreview>
                  <FileUpload.ItemName class={styles.ItemName} />
                  <FileUpload.ItemSizeText class={styles.ItemSizeText} />
                  <FileUpload.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                    <X />
                  </FileUpload.ItemDeleteTrigger>
                </FileUpload.Item>
              }
            </FileUpload.ItemGroup>
          </div>
        }

        if (@context.rejectedFiles.length > 0) {
          <div class={styles.Section}>
            <div class={styles.SectionTitle} data-status="rejected">
              <CircleAlert
                style={{
                  width: '0.875rem',
                  height: '0.875rem',
                  display: 'inline',
                  marginRight: '0.25rem',
                  verticalAlign: 'middle',
                }}
              />
              {'Rejected Files'}
            </div>
            <FileUpload.ItemGroup class={styles.ItemGroup}>
              for (const fileRejection of @context.rejectedFiles; key fileRejection.file.name) {
                <FileUpload.Item file={fileRejection.file} class={styles.Item} data-rejected>
                  <div class={styles.ItemPreview}>
                    <CircleAlert />
                  </div>
                  <FileUpload.ItemName class={styles.ItemName} />
                  <FileUpload.ItemSizeText class={styles.ItemSizeText} />
                  <div class={styles.ErrorList}>
                    for (const error of fileRejection.errors; key error) {
                      <div class={styles.ErrorItem}>
                        {errorMessages[error as FileUploadFileError] || error}
                      </div>
                    }
                  </div>
                </FileUpload.Item>
              }
            </FileUpload.ItemGroup>
          </div>
        }
      }
    </FileUpload.Context>

    <FileUpload.HiddenInput />
  </FileUpload.Root>
}

```

### File Transformations

Use `transformFiles` to process files before they're added. Useful for image compression, format conversion, or
resizing.

**Example: transform-files**

```ripple
import { FileUpload } from 'ark-ripple/file-upload';
import { compressAccurately } from 'image-conversion';
import { Image, X } from 'lucide-ripple';
import styles from 'styles/file-upload.module.css';

const transformFiles = async (files: File[]) => {
  return Promise.all(
    files.map(async (file) => {
      if (file.type.startsWith('image/')) {
        try {
          const blob = await compressAccurately(file, 200);
          return new File([blob], file.name, { type: blob.type });
        } catch (error) {
          console.error('Compression failed for:', file.name, error);
          return file;
        }
      }
      return file;
    }),
  );
};

export component TransformFiles() {
  <FileUpload.Root accept="image/*" maxFiles={5} {transformFiles} class={styles.Root}>
    <FileUpload.Label class={styles.Label}>{'Upload with Compression'}</FileUpload.Label>
    <FileUpload.Trigger class={styles.Trigger}>
      <Image style={{ width: '1rem', height: '1rem' }} />
      {' Choose Images'}
    </FileUpload.Trigger>
    <FileUpload.ItemGroup class={styles.ItemGroup}>
      <FileUpload.Context>
        component children({ context }) {
          for (const file of @context.acceptedFiles; key file.name) {
            <FileUpload.Item {file} class={styles.Item}>
              <FileUpload.ItemPreview type="image/*" class={styles.ItemPreview}>
                <FileUpload.ItemPreviewImage class={styles.ItemPreviewImage} />
              </FileUpload.ItemPreview>
              <FileUpload.ItemName class={styles.ItemName} />
              <FileUpload.ItemSizeText class={styles.ItemSizeText} />
              <FileUpload.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                <X />
              </FileUpload.ItemDeleteTrigger>
            </FileUpload.Item>
          }
        }
      </FileUpload.Context>
    </FileUpload.ItemGroup>
    <FileUpload.HiddenInput />
  </FileUpload.Root>
}

```

### Field

Use `Field` to add helper text and error handling.

**Example: with-field**

```ripple
import { Field } from 'ark-ripple/field';
import { FileUpload } from 'ark-ripple/file-upload';
import { File, Upload, X } from 'lucide-ripple';
import field from 'styles/field.module.css';
import styles from 'styles/file-upload.module.css';

export component WithField() {
  <Field.Root class={field.Root}>
    <FileUpload.Root maxFiles={5} class={styles.Root}>
      <FileUpload.Label class={styles.Label}>{'Attachments'}</FileUpload.Label>
      <FileUpload.Dropzone class={styles.Dropzone}>
        <Upload class={styles.DropzoneIcon} />
        <div class={styles.DropzoneContent}>
          <span class={styles.DropzoneTitle}>{'Drop files here'}</span>
          <span class={styles.DropzoneDescription}>{'or click to browse'}</span>
        </div>
      </FileUpload.Dropzone>
      <FileUpload.ItemGroup class={styles.ItemGroup}>
        <FileUpload.Context>
          component children({ context }) {
            for (const file of @context.acceptedFiles; key file.name) {
              <FileUpload.Item {file} class={styles.Item}>
                <FileUpload.ItemPreview type="image/*" class={styles.ItemPreview}>
                  <FileUpload.ItemPreviewImage class={styles.ItemPreviewImage} />
                </FileUpload.ItemPreview>
                <FileUpload.ItemPreview type=".*" class={styles.ItemPreview}>
                  <File />
                </FileUpload.ItemPreview>
                <FileUpload.ItemName class={styles.ItemName} />
                <FileUpload.ItemSizeText class={styles.ItemSizeText} />
                <FileUpload.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                  <X />
                </FileUpload.ItemDeleteTrigger>
              </FileUpload.Item>
            }
          }
        </FileUpload.Context>
      </FileUpload.ItemGroup>
      <FileUpload.HiddenInput data-testid="input" />
    </FileUpload.Root>
    <Field.HelperText class={field.HelperText}>{'Upload up to 5 files'}</Field.HelperText>
    <Field.ErrorText class={field.ErrorText}>{'Please upload at least one file'}</Field.ErrorText>
  </Field.Root>
}

```

### Root Provider

An alternative way to control the file upload is to use the `RootProvider` component and the `useFileUpload` hook. This
way you can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { FileUpload, useFileUpload } from 'ark-ripple/file-upload';
import { File, Upload, X } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/file-upload.module.css';

export component RootProvider() {
  const fileUpload = useFileUpload({ maxFiles: 5 });

  <div class="stack">
    <button class={button.Root} onClick={() => @fileUpload.clearFiles()}>{'Clear Files'}</button>
    <FileUpload.RootProvider value={fileUpload} class={styles.Root}>
      <FileUpload.Label class={styles.Label}>{'File Upload'}</FileUpload.Label>
      <FileUpload.Dropzone class={styles.Dropzone}>
        <Upload class={styles.DropzoneIcon} />
        <div class={styles.DropzoneContent}>
          <span class={styles.DropzoneTitle}>{'Drop files here'}</span>
          <span class={styles.DropzoneDescription}>{'or click to browse'}</span>
        </div>
      </FileUpload.Dropzone>
      <FileUpload.ItemGroup class={styles.ItemGroup}>
        <FileUpload.Context>
          component children({ context }) {
            for (const file of @context.acceptedFiles; key file.name) {
              <FileUpload.Item {file} class={styles.Item}>
                <FileUpload.ItemPreview type="image/*" class={styles.ItemPreview}>
                  <FileUpload.ItemPreviewImage class={styles.ItemPreviewImage} />
                </FileUpload.ItemPreview>
                <FileUpload.ItemPreview type=".*" class={styles.ItemPreview}>
                  <File />
                </FileUpload.ItemPreview>
                <FileUpload.ItemName class={styles.ItemName} />
                <FileUpload.ItemSizeText class={styles.ItemSizeText} />
                <FileUpload.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                  <X />
                </FileUpload.ItemDeleteTrigger>
              </FileUpload.Item>
            }
          }
        </FileUpload.Context>
      </FileUpload.ItemGroup>
      <FileUpload.HiddenInput />
    </FileUpload.RootProvider>
  </div>
}

```

### Pasting Files

Use `setClipboardFiles` to enable pasting images from the clipboard.

**Example: pasting-files**

```ripple
import { FileUpload, useFileUpload } from 'ark-ripple/file-upload';
import { Clipboard, X } from 'lucide-ripple';
import field from 'styles/field.module.css';
import styles from 'styles/file-upload.module.css';

export component PastingFiles() {
  const fileUpload = useFileUpload({ maxFiles: 3, accept: 'image/*' });

  <FileUpload.RootProvider value={fileUpload} class={styles.Root}>
    <FileUpload.Label class={styles.Label}>
      <Clipboard
        style={{
          width: '1rem',
          height: '1rem',
          display: 'inline',
          marginRight: '0.25rem',
          verticalAlign: 'middle',
        }}
      />
      {'Upload with Paste'}
    </FileUpload.Label>
    <textarea
      class={field.Textarea}
      placeholder="Paste an image here (Ctrl/Cmd + V)"
      onPaste={(e) => {
        @fileUpload.setClipboardFiles((e as ClipboardEvent).clipboardData!);
      }}
    />
    <FileUpload.ItemGroup class={styles.ItemGroup}>
      for (const file of @fileUpload.acceptedFiles; key file.name) {
        <FileUpload.Item {file} class={styles.Item}>
          <FileUpload.ItemPreview type="image/*" class={styles.ItemPreview}>
            <FileUpload.ItemPreviewImage class={styles.ItemPreviewImage} />
          </FileUpload.ItemPreview>
          <FileUpload.ItemName class={styles.ItemName} />
          <FileUpload.ItemSizeText class={styles.ItemSizeText} />
          <FileUpload.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
            <X />
          </FileUpload.ItemDeleteTrigger>
        </FileUpload.Item>
      }
    </FileUpload.ItemGroup>
    <FileUpload.HiddenInput />
  </FileUpload.RootProvider>
}

```

### Media Capture

Use `capture` to access the device camera. Set to `"environment"` for back camera or `"user"` for front camera.

**Example: media-capture**

```ripple
import { FileUpload } from 'ark-ripple/file-upload';
import { Camera, File, X } from 'lucide-ripple';
import styles from 'styles/file-upload.module.css';

export component MediaCapture() {
  <FileUpload.Root capture="environment" class={styles.Root}>
    <FileUpload.Label class={styles.Label}>{'Capture Photo'}</FileUpload.Label>
    <FileUpload.Trigger class={styles.Trigger}>
      <Camera style={{ width: '1rem', height: '1rem' }} />
      {' Open Camera'}
    </FileUpload.Trigger>
    <FileUpload.ItemGroup class={styles.ItemGroup}>
      <FileUpload.Context>
        component children({ context }) {
          for (const file of @context.acceptedFiles; key file.name) {
            <FileUpload.Item {file} class={styles.Item}>
              <FileUpload.ItemPreview type="image/*" class={styles.ItemPreview}>
                <FileUpload.ItemPreviewImage class={styles.ItemPreviewImage} />
              </FileUpload.ItemPreview>
              <FileUpload.ItemPreview type=".*" class={styles.ItemPreview}>
                <File />
              </FileUpload.ItemPreview>
              <FileUpload.ItemName class={styles.ItemName}>
                {file.webkitRelativePath || file.name}
              </FileUpload.ItemName>
              <FileUpload.ItemSizeText class={styles.ItemSizeText} />
              <FileUpload.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                <X />
              </FileUpload.ItemDeleteTrigger>
            </FileUpload.Item>
          }
        }
      </FileUpload.Context>
    </FileUpload.ItemGroup>
    <FileUpload.HiddenInput />
  </FileUpload.Root>
}

```

### Rejected Files

Access `rejectedFiles` from the context to display validation errors.

**Example: rejected-files**

```ripple
import { FileUpload } from 'ark-ripple/file-upload';
import { CircleAlert, CircleCheck, Upload, X } from 'lucide-ripple';
import styles from 'styles/file-upload.module.css';

export component RejectedFiles() {
  <FileUpload.Root
    maxFiles={2}
    class={styles.Root}
    onFileReject={(details) => {
      console.log('Rejected files:', details);
    }}
  >
    <FileUpload.Label class={styles.Label}>{'Upload Files (Max 2)'}</FileUpload.Label>
    <FileUpload.Dropzone class={styles.Dropzone}>
      <Upload class={styles.DropzoneIcon} />
      <div class={styles.DropzoneContent}>
        <span class={styles.DropzoneTitle}>{'Drop files here'}</span>
        <span class={styles.DropzoneDescription}>{'Maximum 2 files allowed'}</span>
      </div>
    </FileUpload.Dropzone>

    <FileUpload.Context>
      component children({ context }) {
        if (@context.acceptedFiles.length > 0) {
          <div class={styles.Section}>
            <div class={styles.SectionTitle} data-status="accepted">
              <CircleCheck
                style={{
                  width: '0.875rem',
                  height: '0.875rem',
                  display: 'inline',
                  marginRight: '0.25rem',
                  verticalAlign: 'middle',
                }}
              />
              {'Accepted Files'}
            </div>
            <FileUpload.ItemGroup type="accepted" class={styles.ItemGroup}>
              for (const file of @context.acceptedFiles; key file.name) {
                <FileUpload.Item {file} class={styles.Item}>
                  <FileUpload.ItemPreview type="image/*" class={styles.ItemPreview}>
                    <FileUpload.ItemPreviewImage class={styles.ItemPreviewImage} />
                  </FileUpload.ItemPreview>
                  <FileUpload.ItemName class={styles.ItemName} />
                  <FileUpload.ItemSizeText class={styles.ItemSizeText} />
                  <FileUpload.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                    <X />
                  </FileUpload.ItemDeleteTrigger>
                </FileUpload.Item>
              }
            </FileUpload.ItemGroup>
          </div>
        }

        if (@context.rejectedFiles.length > 0) {
          <div class={styles.Section}>
            <div class={styles.SectionTitle} data-status="rejected">
              <CircleAlert
                style={{
                  width: '0.875rem',
                  height: '0.875rem',
                  display: 'inline',
                  marginRight: '0.25rem',
                  verticalAlign: 'middle',
                }}
              />
              {'Rejected Files'}
            </div>
            <FileUpload.ItemGroup type="rejected" class={styles.ItemGroup}>
              for (const { file, errors } of @context.rejectedFiles; key file.name) {
                <FileUpload.Item {file} class={styles.Item} data-rejected>
                  <div class={styles.ItemPreview}>
                    <CircleAlert />
                  </div>
                  <FileUpload.ItemName class={styles.ItemName} />
                  <FileUpload.ItemSizeText class={styles.ItemSizeText} />
                  <div class={styles.ErrorList}>
                    for (const error of errors; key error) {
                      <span class={styles.ErrorItem}>{error}</span>
                    }
                  </div>
                </FileUpload.Item>
              }
            </FileUpload.ItemGroup>
          </div>
        }
      }
    </FileUpload.Context>

    <FileUpload.HiddenInput />
  </FileUpload.Root>
}

```

## Guides

### File Previews

Use `ItemPreview` with type matching to show appropriate previews based on file format.

- `type="image/*"`: Shows image thumbnails using `ItemPreviewImage`
- `type="video/*"`: For video file previews
- `type="application/pdf"`: For PDF files
- `type=".*"`: Generic fallback for any file type

```tsx
<FileUpload.ItemPreview type="image/*">
  <FileUpload.ItemPreviewImage />
</FileUpload.ItemPreview>

<FileUpload.ItemPreview type="video/*">
  <VideoIcon />
</FileUpload.ItemPreview>

<FileUpload.ItemPreview type="application/pdf">
  <PdfIcon />
</FileUpload.ItemPreview>

<FileUpload.ItemPreview type=".*">
  <FileIcon />
</FileUpload.ItemPreview>
```

### Disable Dropzone

To disable drag-and-drop functionality, set `allowDrop` to `false`.

```tsx
<FileUpload.Root allowDrop={false}>{/* ... */}</FileUpload.Root>
```

### Prevent Document Drop

By default, we prevent accidental navigation when files are dropped outside the dropzone. Set `preventDocumentDrop` to
`false` to disable this.

```tsx
<FileUpload.Root preventDocumentDrop={false}>{/* ... */}</FileUpload.Root>
```

### Prevent Double Open

Use `disableClick` on `Dropzone` when delegating clicks to a nested `Trigger`. This prevents the file picker from
opening twice.

```tsx
<FileUpload.Dropzone disableClick>
  <FileUpload.Trigger>Choose Files</FileUpload.Trigger>
  Drag files here
</FileUpload.Dropzone>
```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `accept` | `Record<string, string[]> | FileMimeType | FileMimeType[]` | No | The accept file types |
| `acceptedFiles` | `File[]` | No | The controlled accepted files |
| `allowDrop` | `boolean` | No | Whether to allow drag and drop in the dropzone element |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `capture` | `'user' | 'environment'` | No | The default camera to use when capturing media |
| `defaultAcceptedFiles` | `File[]` | No | The default accepted files when rendered.
Use when you don't need to control the accepted files of the input. |
| `directory` | `boolean` | No | Whether to accept directories, only works in webkit browsers |
| `disabled` | `boolean` | No | Whether the file input is disabled |
| `ids` | `Partial<{
  root: string
  dropzone: string
  hiddenInput: string
  trigger: string
  label: string
  item: (id: string) => string
  itemName: (id: string) => string
  itemSizeText: (id: string) => string
  itemPreview: (id: string) => string
  itemDeleteTrigger: (id: string) => string
}>` | No | The ids of the elements. Useful for composition. |
| `invalid` | `boolean` | No | Whether the file input is invalid |
| `locale` | `string` | No | The current locale. Based on the BCP 47 definition. |
| `maxFiles` | `number` | No | The maximum number of files |
| `maxFileSize` | `number` | No | The maximum file size in bytes |
| `minFileSize` | `number` | No | The minimum file size in bytes |
| `name` | `string` | No | The name of the underlying file input |
| `onFileAccept` | `(details: FileAcceptDetails) => void` | No | Function called when the file is accepted |
| `onFileChange` | `(details: FileChangeDetails) => void` | No | Function called when the value changes, whether accepted or rejected |
| `onFileReject` | `(details: FileRejectDetails) => void` | No | Function called when the file is rejected |
| `preventDocumentDrop` | `boolean` | No | Whether to prevent the drop event on the document |
| `readOnly` | `boolean` | No | Whether the file input is read-only |
| `required` | `boolean` | No | Whether the file input is required |
| `transformFiles` | `(files: File[]) => Promise<File[]>` | No | Function to transform the accepted files to apply transformations |
| `translations` | `IntlTranslations` | No | The localized messages to use. |
| `validate` | `(file: File, details: FileValidateDetails) => FileError[] | null` | No | Function to validate a file |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | file-upload |
| `[data-part]` | root |
| `[data-disabled]` | Present when disabled |
| `[data-readonly]` | Present when read-only |
| `[data-dragging]` | Present when in the dragging state |


**ClearTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ClearTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | file-upload |
| `[data-part]` | clear-trigger |
| `[data-disabled]` | Present when disabled |
| `[data-readonly]` | Present when read-only |


**Dropzone Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `disableClick` | `boolean` | No | Whether to disable the click event on the dropzone |


**Dropzone Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | file-upload |
| `[data-part]` | dropzone |
| `[data-invalid]` | Present when invalid |
| `[data-disabled]` | Present when disabled |
| `[data-readonly]` | Present when read-only |
| `[data-dragging]` | Present when in the dragging state |


**HiddenInput Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemDeleteTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemDeleteTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | file-upload |
| `[data-part]` | item-delete-trigger |
| `[data-disabled]` | Present when disabled |
| `[data-readonly]` | Present when read-only |
| `[data-type]` | The type of the item |


**ItemGroup Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `type` | `ItemType` | No |  |


**ItemGroup Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | file-upload |
| `[data-part]` | item-group |
| `[data-disabled]` | Present when disabled |
| `[data-type]` | The type of the item |


**ItemName Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemName Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | file-upload |
| `[data-part]` | item-name |
| `[data-disabled]` | Present when disabled |
| `[data-type]` | The type of the item |


**ItemPreviewImage Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemPreviewImage Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | file-upload |
| `[data-part]` | item-preview-image |
| `[data-disabled]` | Present when disabled |
| `[data-type]` | The type of the item |


**ItemPreview Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `type` | `string` | No | The file type to match against. Matches all file types by default. |


**ItemPreview Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | file-upload |
| `[data-part]` | item-preview |
| `[data-disabled]` | Present when disabled |
| `[data-type]` | The type of the item |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `file` | `File` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Item Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | file-upload |
| `[data-part]` | item |
| `[data-disabled]` | Present when disabled |
| `[data-type]` | The type of the item |


**ItemSizeText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemSizeText Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | file-upload |
| `[data-part]` | item-size-text |
| `[data-disabled]` | Present when disabled |
| `[data-type]` | The type of the item |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | file-upload |
| `[data-part]` | label |
| `[data-disabled]` | Present when disabled |
| `[data-required]` | Present when required |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseFileUploadReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | file-upload |
| `[data-part]` | trigger |
| `[data-disabled]` | Present when disabled |
| `[data-readonly]` | Present when read-only |
| `[data-invalid]` | Present when invalid |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `dragging` | `boolean` | Whether the user is dragging something over the root element |
| `focused` | `boolean` | Whether the user is focused on the dropzone element |
| `disabled` | `boolean` | Whether the file input is disabled |
| `readOnly` | `boolean` | Whether the file input is in read-only mode |
| `transforming` | `boolean` | Whether files are currently being transformed via `transformFiles` |
| `maxFilesReached` | `boolean` | Whether the maximum number of files has been reached |
| `remainingFiles` | `number` | The number of files that can still be added |
| `openFilePicker` | `VoidFunction` | Function to open the file dialog |
| `deleteFile` | `(file: File, type?: ItemType) => void` | Function to delete the file from the list |
| `acceptedFiles` | `File[]` | The accepted files that have been dropped or selected |
| `rejectedFiles` | `FileRejection[]` | The files that have been rejected |
| `setFiles` | `(files: File[]) => void` | Sets the accepted files |
| `clearFiles` | `VoidFunction` | Clears the accepted files |
| `clearRejectedFiles` | `VoidFunction` | Clears the rejected files |
| `getFileSize` | `(file: File) => string` | Returns the formatted file size (e.g. 1.2MB) |
| `createFileUrl` | `(file: File, cb: (url: string) => void) => VoidFunction` | Returns the preview url of a file.
Returns a function to revoke the url. |
| `setClipboardFiles` | `(dt: DataTransfer) => boolean` | Sets the clipboard files
Returns `true` if the clipboard data contains files, `false` otherwise. |



# Floating Panel 



## Anatomy



```tsx
<FloatingPanel.Root>
  <FloatingPanel.Trigger />
  <FloatingPanel.Positioner>
    <FloatingPanel.Content>
      <FloatingPanel.DragTrigger>
        <FloatingPanel.Header>
          <FloatingPanel.Title />
          <FloatingPanel.Control>
            <FloatingPanel.StageTrigger />
            <FloatingPanel.CloseTrigger />
          </FloatingPanel.Control>
        </FloatingPanel.Header>
      </FloatingPanel.DragTrigger>
      <FloatingPanel.Body />
      <FloatingPanel.ResizeTrigger />
    </FloatingPanel.Content>
  </FloatingPanel.Positioner>
</FloatingPanel.Root>
```

## Examples

**Example: basic**

```ripple
import { FloatingPanel } from 'ark-ripple/floating-panel';
import { Portal } from 'ark-ripple/portal';
import { GripVertical, Minus, Maximize2, ArrowDownLeft, X } from 'lucide-ripple';
import styles from 'styles/floating-panel.module.css';

export component Basic() {
  <FloatingPanel.Root>
    <FloatingPanel.Trigger class={styles.Trigger}>{'Toggle Panel'}</FloatingPanel.Trigger>
    <Portal>
      <FloatingPanel.Positioner class={styles.Positioner}>
        <FloatingPanel.Content class={styles.Content}>
          <FloatingPanel.DragTrigger>
            <FloatingPanel.Header class={styles.Header}>
              <FloatingPanel.Title class={styles.Title}>
                <GripVertical />
                {'Floating Panel'}
              </FloatingPanel.Title>
              <FloatingPanel.Control class={styles.Control}>
                <FloatingPanel.StageTrigger stage="minimized" class={styles.ControlButton}>
                  <Minus />
                </FloatingPanel.StageTrigger>
                <FloatingPanel.StageTrigger stage="maximized" class={styles.ControlButton}>
                  <Maximize2 />
                </FloatingPanel.StageTrigger>
                <FloatingPanel.StageTrigger stage="default" class={styles.ControlButton}>
                  <ArrowDownLeft />
                </FloatingPanel.StageTrigger>
                <FloatingPanel.CloseTrigger class={styles.ControlButton}>
                  <X />
                </FloatingPanel.CloseTrigger>
              </FloatingPanel.Control>
            </FloatingPanel.Header>
          </FloatingPanel.DragTrigger>
          <FloatingPanel.Body class={styles.Body}>
            <p>{'Some content'}</p>
          </FloatingPanel.Body>

          <FloatingPanel.ResizeTrigger axis="n" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="e" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="w" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="s" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="ne" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="se" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="sw" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="nw" class={styles.ResizeTrigger} />
        </FloatingPanel.Content>
      </FloatingPanel.Positioner>
    </Portal>
  </FloatingPanel.Root>
}

```

### Controlled size

To control the size of the floating panel programmatically, you can pass the `size` `onResize` prop to the machine.

**Example: controlled-size**

```ripple
import { FloatingPanel } from 'ark-ripple/floating-panel';
import { Portal } from 'ark-ripple/portal';
import { GripVertical, Minus, Maximize2, ArrowDownLeft, X } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/floating-panel.module.css';

export component ControlledSize() {
  let size = track({ width: 400, height: 300 });

  <FloatingPanel.Root
    {size}
    onSizeChange={(e) => {
      @size = e.size;
    }}
  >
    <FloatingPanel.Trigger class={styles.Trigger}>{'Toggle Panel'}</FloatingPanel.Trigger>
    <Portal>
      <FloatingPanel.Positioner class={styles.Positioner}>
        <FloatingPanel.Content class={styles.Content}>
          <FloatingPanel.DragTrigger>
            <FloatingPanel.Header class={styles.Header}>
              <FloatingPanel.Title class={styles.Title}>
                <GripVertical />
                {'Floating Panel'}
              </FloatingPanel.Title>
              <FloatingPanel.Control class={styles.Control}>
                <FloatingPanel.StageTrigger stage="minimized" class={styles.ControlButton}>
                  <Minus />
                </FloatingPanel.StageTrigger>
                <FloatingPanel.StageTrigger stage="maximized" class={styles.ControlButton}>
                  <Maximize2 />
                </FloatingPanel.StageTrigger>
                <FloatingPanel.StageTrigger stage="default" class={styles.ControlButton}>
                  <ArrowDownLeft />
                </FloatingPanel.StageTrigger>
                <FloatingPanel.CloseTrigger class={styles.ControlButton}>
                  <X />
                </FloatingPanel.CloseTrigger>
              </FloatingPanel.Control>
            </FloatingPanel.Header>
          </FloatingPanel.DragTrigger>
          <FloatingPanel.Body class={styles.Body}>
            <p>{'Some content'}</p>
          </FloatingPanel.Body>

          <FloatingPanel.ResizeTrigger axis="n" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="e" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="w" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="s" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="ne" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="se" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="sw" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="nw" class={styles.ResizeTrigger} />
        </FloatingPanel.Content>
      </FloatingPanel.Positioner>
    </Portal>
  </FloatingPanel.Root>
}

```

### Controlled position

To control the position of the floating panel programmatically, you can pass the `position` and `onPositionChange` prop
to the machine.

**Example: controlled-position**

```ripple
import { FloatingPanel } from 'ark-ripple/floating-panel';
import { Portal } from 'ark-ripple/portal';
import { GripVertical, Minus, Maximize2, ArrowDownLeft, X } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/floating-panel.module.css';

export component ControlledPosition() {
  let position = track({ x: 200, y: 200 });

  <FloatingPanel.Root
    {position}
    onPositionChange={(e) => {
      @position = e.position;
    }}
  >
    <FloatingPanel.Trigger class={styles.Trigger}>{'Toggle Panel'}</FloatingPanel.Trigger>
    <Portal>
      <FloatingPanel.Positioner class={styles.Positioner}>
        <FloatingPanel.Content class={styles.Content}>
          <FloatingPanel.DragTrigger>
            <FloatingPanel.Header class={styles.Header}>
              <FloatingPanel.Title class={styles.Title}>
                <GripVertical />
                {'Floating Panel'}
              </FloatingPanel.Title>
              <FloatingPanel.Control class={styles.Control}>
                <FloatingPanel.StageTrigger stage="minimized" class={styles.ControlButton}>
                  <Minus />
                </FloatingPanel.StageTrigger>
                <FloatingPanel.StageTrigger stage="maximized" class={styles.ControlButton}>
                  <Maximize2 />
                </FloatingPanel.StageTrigger>
                <FloatingPanel.StageTrigger stage="default" class={styles.ControlButton}>
                  <ArrowDownLeft />
                </FloatingPanel.StageTrigger>
                <FloatingPanel.CloseTrigger class={styles.ControlButton}>
                  <X />
                </FloatingPanel.CloseTrigger>
              </FloatingPanel.Control>
            </FloatingPanel.Header>
          </FloatingPanel.DragTrigger>
          <FloatingPanel.Body class={styles.Body}>
            <p>{'Some content'}</p>
          </FloatingPanel.Body>

          <FloatingPanel.ResizeTrigger axis="n" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="e" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="w" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="s" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="ne" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="se" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="sw" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="nw" class={styles.ResizeTrigger} />
        </FloatingPanel.Content>
      </FloatingPanel.Positioner>
    </Portal>
  </FloatingPanel.Root>
}

```

### Anchor Position

Use the `getAnchorPosition` function to compute the initial position of the floating panel. This function is called when
the panel is opened and receives the `triggerRect` and `boundaryRect`.

**Example: anchor-position**

```ripple
import { FloatingPanel } from 'ark-ripple/floating-panel';
import { Portal } from 'ark-ripple/portal';
import { GripVertical, Minus, Maximize2, ArrowDownLeft, X } from 'lucide-ripple';
import styles from 'styles/floating-panel.module.css';

export component AnchorPosition() {
  <FloatingPanel.Root
    getAnchorPosition={({ triggerRect }) => {
      if (!triggerRect) return { x: 0, y: 0 };
      return {
        x: triggerRect.x + triggerRect.width / 2,
        y: triggerRect.y + triggerRect.height / 2,
      };
    }}
  >
    <FloatingPanel.Trigger class={styles.Trigger}>{'Toggle Panel'}</FloatingPanel.Trigger>
    <Portal>
      <FloatingPanel.Positioner class={styles.Positioner}>
        <FloatingPanel.Content class={styles.Content}>
          <FloatingPanel.DragTrigger>
            <FloatingPanel.Header class={styles.Header}>
              <FloatingPanel.Title class={styles.Title}>
                <GripVertical />
                {'Floating Panel'}
              </FloatingPanel.Title>
              <FloatingPanel.Control class={styles.Control}>
                <FloatingPanel.StageTrigger stage="minimized" class={styles.ControlButton}>
                  <Minus />
                </FloatingPanel.StageTrigger>
                <FloatingPanel.StageTrigger stage="maximized" class={styles.ControlButton}>
                  <Maximize2 />
                </FloatingPanel.StageTrigger>
                <FloatingPanel.StageTrigger stage="default" class={styles.ControlButton}>
                  <ArrowDownLeft />
                </FloatingPanel.StageTrigger>
                <FloatingPanel.CloseTrigger class={styles.ControlButton}>
                  <X />
                </FloatingPanel.CloseTrigger>
              </FloatingPanel.Control>
            </FloatingPanel.Header>
          </FloatingPanel.DragTrigger>
          <FloatingPanel.Body class={styles.Body}>
            <p>{'Some content'}</p>
          </FloatingPanel.Body>

          <FloatingPanel.ResizeTrigger axis="n" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="e" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="w" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="s" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="ne" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="se" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="sw" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="nw" class={styles.ResizeTrigger} />
        </FloatingPanel.Content>
      </FloatingPanel.Positioner>
    </Portal>
  </FloatingPanel.Root>
}

```

### Open State

To control the open state of the floating panel programmatically, you can pass the `open` and `onOpenChange` prop to the
machine.

**Example: controlled-open**

```ripple
import { FloatingPanel } from 'ark-ripple/floating-panel';
import { Portal } from 'ark-ripple/portal';
import { GripVertical, Minus, Maximize2, ArrowDownLeft, X } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/floating-panel.module.css';

export component ControlledOpen() {
  let open = track(false);

  <FloatingPanel.Root
    {open}
    onOpenChange={(e) => {
      @open = e.open;
    }}
  >
    <FloatingPanel.Trigger class={styles.Trigger}>{'Toggle Panel'}</FloatingPanel.Trigger>
    <Portal>
      <FloatingPanel.Positioner class={styles.Positioner}>
        <FloatingPanel.Content class={styles.Content}>
          <FloatingPanel.DragTrigger>
            <FloatingPanel.Header class={styles.Header}>
              <FloatingPanel.Title class={styles.Title}>
                <GripVertical />
                {'Floating Panel'}
              </FloatingPanel.Title>
              <FloatingPanel.Control class={styles.Control}>
                <FloatingPanel.StageTrigger stage="minimized" class={styles.ControlButton}>
                  <Minus />
                </FloatingPanel.StageTrigger>
                <FloatingPanel.StageTrigger stage="maximized" class={styles.ControlButton}>
                  <Maximize2 />
                </FloatingPanel.StageTrigger>
                <FloatingPanel.StageTrigger stage="default" class={styles.ControlButton}>
                  <ArrowDownLeft />
                </FloatingPanel.StageTrigger>
                <FloatingPanel.CloseTrigger class={styles.ControlButton}>
                  <X />
                </FloatingPanel.CloseTrigger>
              </FloatingPanel.Control>
            </FloatingPanel.Header>
          </FloatingPanel.DragTrigger>
          <FloatingPanel.Body class={styles.Body}>
            <p>{'Some content'}</p>
          </FloatingPanel.Body>

          <FloatingPanel.ResizeTrigger axis="n" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="e" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="w" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="s" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="ne" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="se" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="sw" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="nw" class={styles.ResizeTrigger} />
        </FloatingPanel.Content>
      </FloatingPanel.Positioner>
    </Portal>
  </FloatingPanel.Root>
}

```

### Lazy Mount

To lazy mount the floating panel, you can pass the `lazyMount` prop to the machine.

**Example: lazy-mount**

```ripple
import { FloatingPanel } from 'ark-ripple/floating-panel';
import { Portal } from 'ark-ripple/portal';
import { GripVertical, Minus, Maximize2, ArrowDownLeft, X } from 'lucide-ripple';
import styles from 'styles/floating-panel.module.css';

export component LazyMount() {
  <FloatingPanel.Root lazyMount onExitComplete={() => console.log('onExitComplete invoked')}>
    <FloatingPanel.Trigger class={styles.Trigger}>{'Toggle Panel'}</FloatingPanel.Trigger>
    <Portal>
      <FloatingPanel.Positioner class={styles.Positioner}>
        <FloatingPanel.Content class={styles.Content}>
          <FloatingPanel.DragTrigger>
            <FloatingPanel.Header class={styles.Header}>
              <FloatingPanel.Title class={styles.Title}>
                <GripVertical />
                {'Floating Panel'}
              </FloatingPanel.Title>
              <FloatingPanel.Control class={styles.Control}>
                <FloatingPanel.StageTrigger stage="minimized" class={styles.ControlButton}>
                  <Minus />
                </FloatingPanel.StageTrigger>
                <FloatingPanel.StageTrigger stage="maximized" class={styles.ControlButton}>
                  <Maximize2 />
                </FloatingPanel.StageTrigger>
                <FloatingPanel.StageTrigger stage="default" class={styles.ControlButton}>
                  <ArrowDownLeft />
                </FloatingPanel.StageTrigger>
                <FloatingPanel.CloseTrigger class={styles.ControlButton}>
                  <X />
                </FloatingPanel.CloseTrigger>
              </FloatingPanel.Control>
            </FloatingPanel.Header>
          </FloatingPanel.DragTrigger>
          <FloatingPanel.Body class={styles.Body}>
            <p>{'Some content'}</p>
          </FloatingPanel.Body>

          <FloatingPanel.ResizeTrigger axis="n" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="e" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="w" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="s" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="ne" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="se" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="sw" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="nw" class={styles.ResizeTrigger} />
        </FloatingPanel.Content>
      </FloatingPanel.Positioner>
    </Portal>
  </FloatingPanel.Root>
}

```

### Context

To access the context of the floating panel, you can use the `useFloatingPanelContext` hook or the
`FloatingPanel.Context` component.

**Example: context**

```ripple
import { FloatingPanel } from 'ark-ripple/floating-panel';
import { Portal } from 'ark-ripple/portal';
import { GripVertical, Minus, Maximize2, ArrowDownLeft, X } from 'lucide-ripple';
import styles from 'styles/floating-panel.module.css';

export component Context() {
  <FloatingPanel.Root>
    <FloatingPanel.Trigger class={styles.Trigger}>{'Toggle Panel'}</FloatingPanel.Trigger>
    <FloatingPanel.Context>
      component children({ context }) {
        <p>
          {'floatingPanel is '}
          {@context.open ? 'open' : 'closed'}
        </p>
      }
    </FloatingPanel.Context>
    <Portal>
      <FloatingPanel.Positioner class={styles.Positioner}>
        <FloatingPanel.Content class={styles.Content}>
          <FloatingPanel.DragTrigger>
            <FloatingPanel.Header class={styles.Header}>
              <FloatingPanel.Title class={styles.Title}>
                <GripVertical />
                {'Floating Panel'}
              </FloatingPanel.Title>
              <FloatingPanel.Control class={styles.Control}>
                <FloatingPanel.StageTrigger stage="minimized" class={styles.ControlButton}>
                  <Minus />
                </FloatingPanel.StageTrigger>
                <FloatingPanel.StageTrigger stage="maximized" class={styles.ControlButton}>
                  <Maximize2 />
                </FloatingPanel.StageTrigger>
                <FloatingPanel.StageTrigger stage="default" class={styles.ControlButton}>
                  <ArrowDownLeft />
                </FloatingPanel.StageTrigger>
                <FloatingPanel.CloseTrigger class={styles.ControlButton}>
                  <X />
                </FloatingPanel.CloseTrigger>
              </FloatingPanel.Control>
            </FloatingPanel.Header>
          </FloatingPanel.DragTrigger>
          <FloatingPanel.Body class={styles.Body}>
            <p>{'Some content'}</p>
          </FloatingPanel.Body>

          <FloatingPanel.ResizeTrigger axis="n" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="e" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="w" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="s" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="ne" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="se" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="sw" class={styles.ResizeTrigger} />
          <FloatingPanel.ResizeTrigger axis="nw" class={styles.ResizeTrigger} />
        </FloatingPanel.Content>
      </FloatingPanel.Positioner>
    </Portal>
  </FloatingPanel.Root>
}

```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `allowOverflow` | `boolean` | No | Whether the panel should be strictly contained within the boundary when dragging |
| `closeOnEscape` | `boolean` | No | Whether the panel should close when the escape key is pressed |
| `defaultOpen` | `boolean` | No | The initial open state of the panel when rendered.
Use when you don't need to control the open state of the panel. |
| `defaultPosition` | `Point` | No | The initial position of the panel when rendered.
Use when you don't need to control the position of the panel. |
| `defaultSize` | `Size` | No | The default size of the panel |
| `dir` | `'ltr' | 'rtl'` | No | The document's text/writing direction. |
| `disabled` | `boolean` | No | Whether the panel is disabled |
| `draggable` | `boolean` | No | Whether the panel is draggable |
| `getAnchorPosition` | `(details: AnchorPositionDetails) => Point` | No | Function that returns the initial position of the panel when it is opened.
If provided, will be used instead of the default position. |
| `getBoundaryEl` | `() => HTMLElement | null` | No | The boundary of the panel. Useful for recalculating the boundary rect when
the it is resized. |
| `gridSize` | `number` | No | The snap grid for the panel |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{ trigger: string; positioner: string; content: string; title: string; header: string }>` | No | The ids of the elements in the floating panel. Useful for composition. |
| `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `lockAspectRatio` | `boolean` | No | Whether the panel is locked to its aspect ratio |
| `maxSize` | `Size` | No | The maximum size of the panel |
| `minSize` | `Size` | No | The minimum size of the panel |
| `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state |
| `onOpenChange` | `(details: OpenChangeDetails) => void` | No | Function called when the panel is opened or closed |
| `onPositionChange` | `(details: PositionChangeDetails) => void` | No | Function called when the position of the panel changes via dragging |
| `onPositionChangeEnd` | `(details: PositionChangeDetails) => void` | No | Function called when the position of the panel changes via dragging ends |
| `onSizeChange` | `(details: SizeChangeDetails) => void` | No | Function called when the size of the panel changes via resizing |
| `onSizeChangeEnd` | `(details: SizeChangeDetails) => void` | No | Function called when the size of the panel changes via resizing ends |
| `onStageChange` | `(details: StageChangeDetails) => void` | No | Function called when the stage of the panel changes |
| `open` | `boolean` | No | The controlled open state of the panel |
| `persistRect` | `boolean` | No | Whether the panel size and position should be preserved when it is closed |
| `position` | `Point` | No | The controlled position of the panel |
| `present` | `boolean` | No | Whether the node is present (controlled by the user) |
| `resizable` | `boolean` | No | Whether the panel is resizable |
| `size` | `Size` | No | The size of the panel |
| `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. |
| `strategy` | `'absolute' | 'fixed'` | No | The strategy to use for positioning |
| `translations` | `IntlTranslations` | No | The translations for the floating panel. |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


**Body Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Body Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | floating-panel |
| `[data-part]` | body |
| `[data-dragging]` | Present when in the dragging state |
| `[data-minimized]` | Present when minimized |
| `[data-maximized]` | Present when maximized |
| `[data-staged]` | Present when not in default stage |


**CloseTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | floating-panel |
| `[data-part]` | content |
| `[data-state]` | "open" | "closed" |
| `[data-dragging]` | Present when in the dragging state |
| `[data-topmost]` | Present when topmost |
| `[data-behind]` | Present when not topmost |
| `[data-minimized]` | Present when minimized |
| `[data-maximized]` | Present when maximized |
| `[data-staged]` | Present when not in default stage |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | floating-panel |
| `[data-part]` | control |
| `[data-disabled]` | Present when disabled |
| `[data-stage]` | The stage of the control |
| `[data-minimized]` | Present when minimized |
| `[data-maximized]` | Present when maximized |
| `[data-staged]` | Present when not in default stage |


**DragTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**DragTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | floating-panel |
| `[data-part]` | drag-trigger |
| `[data-disabled]` | Present when disabled |


**Header Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Header Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | floating-panel |
| `[data-part]` | header |
| `[data-dragging]` | Present when in the dragging state |
| `[data-topmost]` | Present when topmost |
| `[data-behind]` | Present when not topmost |
| `[data-minimized]` | Present when minimized |
| `[data-maximized]` | Present when maximized |
| `[data-staged]` | Present when not in default stage |


**Positioner Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Positioner CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--width` | The width of the element |
| `--height` | The height of the element |
| `--x` | The x position for transform |
| `--y` | The y position for transform |
| `--reference-width` | The width of the reference element |
| `--reference-height` | The height of the root |
| `--available-width` | The available width in viewport |
| `--available-height` | The available height in viewport |
| `--z-index` | The z-index value |
| `--transform-origin` | The transform origin for animations |


**ResizeTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `axis` | `ResizeTriggerAxis` | Yes | The axis of the resize handle |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ResizeTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | floating-panel |
| `[data-part]` | resize-trigger |
| `[data-disabled]` | Present when disabled |
| `[data-axis]` | The axis to resize |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseFloatingPanelReturn` | Yes |  |
| `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state |
| `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


**StageTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `stage` | `Stage` | Yes | The stage of the panel |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**StageTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | floating-panel |
| `[data-part]` | stage-trigger |
| `[data-stage]` | The stage of the stagetrigger |


**Title Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | floating-panel |
| `[data-part]` | trigger |
| `[data-state]` | "open" | "closed" |
| `[data-dragging]` | Present when in the dragging state |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `open` | `boolean` | Whether the panel is open |
| `setOpen` | `(open: boolean) => void` | Function to open or close the panel |
| `dragging` | `boolean` | Whether the panel is being dragged |
| `resizing` | `boolean` | Whether the panel is being resized |
| `position` | `Point` | The position of the panel |
| `setPosition` | `(position: Point) => void` | Function to set the position of the panel |
| `size` | `Size` | The size of the panel |
| `setSize` | `(size: Size) => void` | Function to set the size of the panel |
| `minimize` | `VoidFunction` | Function to minimize the panel |
| `maximize` | `VoidFunction` | Function to maximize the panel |
| `restore` | `VoidFunction` | Function to restore the panel before it was minimized or maximized |
| `resizable` | `boolean` | Whether the panel is resizable |
| `draggable` | `boolean` | Whether the panel is draggable |



# Hover Card 



## Anatomy



```tsx
<HoverCard.Root>
  <HoverCard.Trigger />
  <HoverCard.Positioner>
    <HoverCard.Arrow>
      <HoverCard.ArrowTip />
    </HoverCard.Arrow>
    <HoverCard.Content />
  </HoverCard.Positioner>
</HoverCard.Root>
```

## Examples

**Example: basic**

```ripple
import { HoverCard } from 'ark-ripple/hover-card';
import { Portal } from 'ark-ripple/portal';
import styles from 'styles/hover-card.module.css';

export component Basic() {
  <HoverCard.Root>
    <p>
      {'Liked by '}
      <HoverCard.Trigger class={styles.Trigger}>
        component asChild({ propsFn }) {
          <a {...propsFn({ href: '#profile' })}>{'@sarah_chen'}</a>
        }
      </HoverCard.Trigger>
      {' and 3 others'}
    </p>
    <Portal>
      <HoverCard.Positioner>
        <HoverCard.Content class={styles.Content}>
          <HoverCard.Arrow class={styles.Arrow}>
            <HoverCard.ArrowTip class={styles.ArrowTip} />
          </HoverCard.Arrow>
          <div class={styles.Body}>
            <div class={styles.Header}>
              <img class={styles.Avatar} src="https://i.pravatar.cc/300?u=sarah" alt="Sarah Chen" />
              <button type="button" class={styles.FollowButton}>{'Follow'}</button>
            </div>
            <div>
              <p class={styles.Name}>{'Sarah Chen'}</p>
              <p class={styles.Username}>{'@sarah_chen'}</p>
            </div>
            <p class={styles.Bio}>
              {'Design Engineer at Acme Inc. Building beautiful interfaces and design systems.'}
            </p>
            <div class={styles.Stats}>
              <div class={styles.Stat}>
                <span class={styles.StatValue}>{'2,456'}</span>
                <span class={styles.StatLabel}>{'Following'}</span>
              </div>
              <div class={styles.Stat}>
                <span class={styles.StatValue}>{'14.5K'}</span>
                <span class={styles.StatLabel}>{'Followers'}</span>
              </div>
            </div>
          </div>
        </HoverCard.Content>
      </HoverCard.Positioner>
    </Portal>
  </HoverCard.Root>
}

```

### Controlled

The controlled `HoverCard` component provides an interface for managing the state of the hover card using the `open` and
`onOpenChange` props:

**Example: controlled**

```ripple
import { HoverCard } from 'ark-ripple/hover-card';
import { Portal } from 'ark-ripple/portal';
import { track } from 'ripple';
import button from 'styles/button.module.css';
import styles from 'styles/hover-card.module.css';

export component Controlled() {
  let open = track(false);

  <div class="stack">
    <button
      type="button"
      class={button.Root}
      onClick={() => {
        @open = !@open;
      }}
    >
      {'Toggle'}
    </button>
    <HoverCard.Root
      {open}
      onOpenChange={(e) => {
        @open = e.open;
      }}
    >
      <p>
        {'Liked by '}
        <HoverCard.Trigger class={styles.Trigger}>
          component asChild({ propsFn }) {
            <a {...propsFn({ href: '#profile' })}>{'@sarah_chen'}</a>
          }
        </HoverCard.Trigger>
        {' and 3 others'}
      </p>
      <Portal>
        <HoverCard.Positioner>
          <HoverCard.Content class={styles.Content}>
            <HoverCard.Arrow class={styles.Arrow}>
              <HoverCard.ArrowTip class={styles.ArrowTip} />
            </HoverCard.Arrow>
            <div class={styles.Body}>
              <img class={styles.Avatar} src="https://i.pravatar.cc/300?u=sarah" alt="Sarah Chen" />
              <div>
                <p class={styles.Name}>{'Sarah Chen'}</p>
                <p class={styles.Username}>{'@sarah_chen'}</p>
              </div>
              <p class={styles.Bio}>{'Design Engineer at Acme Inc.'}</p>
            </div>
          </HoverCard.Content>
        </HoverCard.Positioner>
      </Portal>
    </HoverCard.Root>
  </div>
}

```

### Root Provider

An alternative way to control the hover card is to use the `RootProvider` component and the `useHoverCard` hook. This
way you can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { HoverCard, useHoverCard } from 'ark-ripple/hover-card';
import { Portal } from 'ark-ripple/portal';
import styles from 'styles/hover-card.module.css';

export component RootProvider() {
  const hoverCard = useHoverCard();

  <div class="stack">
    <output>
      {'Open: '}
      {String(@hoverCard.open)}
    </output>
    <HoverCard.RootProvider value={hoverCard}>
      <p>
        {'Liked by '}
        <HoverCard.Trigger class={styles.Trigger}>
          component asChild({ propsFn }) {
            <a {...propsFn({ href: '#profile' })}>{'@sarah_chen'}</a>
          }
        </HoverCard.Trigger>
        {' and 3 others'}
      </p>
      <Portal>
        <HoverCard.Positioner>
          <HoverCard.Content class={styles.Content}>
            <HoverCard.Arrow class={styles.Arrow}>
              <HoverCard.ArrowTip class={styles.ArrowTip} />
            </HoverCard.Arrow>
            <div class={styles.Body}>
              <img class={styles.Avatar} src="https://i.pravatar.cc/300?u=sarah" alt="Sarah Chen" />
              <div>
                <p class={styles.Name}>{'Sarah Chen'}</p>
                <p class={styles.Username}>{'@sarah_chen'}</p>
              </div>
              <p class={styles.Bio}>{'Design Engineer at Acme Inc.'}</p>
            </div>
          </HoverCard.Content>
        </HoverCard.Positioner>
      </Portal>
    </HoverCard.RootProvider>
  </div>
}

```

### Delay

Control the open and close delay of the hover card using the `openDelay` and `closeDelay` props:

**Example: delay**

```ripple
import { HoverCard } from 'ark-ripple/hover-card';
import { Portal } from 'ark-ripple/portal';
import styles from 'styles/hover-card.module.css';

export component Delay() {
  <HoverCard.Root openDelay={200} closeDelay={500}>
    <p>
      {'Liked by '}
      <HoverCard.Trigger class={styles.Trigger}>
        component asChild({ propsFn }) {
          <a {...propsFn({ href: '#profile' })}>{'@sarah_chen'}</a>
        }
      </HoverCard.Trigger>
      {' and 3 others'}
    </p>
    <Portal>
      <HoverCard.Positioner>
        <HoverCard.Content class={styles.Content}>
          <HoverCard.Arrow class={styles.Arrow}>
            <HoverCard.ArrowTip class={styles.ArrowTip} />
          </HoverCard.Arrow>
          <div class={styles.Body}>
            <img class={styles.Avatar} src="https://i.pravatar.cc/300?u=sarah" alt="Sarah Chen" />
            <div>
              <p class={styles.Name}>{'Sarah Chen'}</p>
              <p class={styles.Username}>{'@sarah_chen'}</p>
            </div>
            <p class={styles.Bio}>{'Design Engineer at Acme Inc.'}</p>
          </div>
        </HoverCard.Content>
      </HoverCard.Positioner>
    </Portal>
  </HoverCard.Root>
}

```

### Positioning

The `HoverCard` component can be customized in its placement and distance from the trigger element through the
`positioning` prop:

**Example: positioning**

```ripple
import { HoverCard } from 'ark-ripple/hover-card';
import { Portal } from 'ark-ripple/portal';
import styles from 'styles/hover-card.module.css';

export component Positioning() {
  <HoverCard.Root positioning={{ placement: 'right', gutter: 12 }}>
    <p>
      {'Liked by '}
      <HoverCard.Trigger class={styles.Trigger}>
        component asChild({ propsFn }) {
          <a {...propsFn({ href: '#profile' })}>{'@sarah_chen'}</a>
        }
      </HoverCard.Trigger>
      {' and 3 others'}
    </p>
    <Portal>
      <HoverCard.Positioner>
        <HoverCard.Content class={styles.Content}>
          <HoverCard.Arrow class={styles.Arrow}>
            <HoverCard.ArrowTip class={styles.ArrowTip} />
          </HoverCard.Arrow>
          <div class={styles.Body}>
            <img class={styles.Avatar} src="https://i.pravatar.cc/300?u=sarah" alt="Sarah Chen" />
            <div>
              <p class={styles.Name}>{'Sarah Chen'}</p>
              <p class={styles.Username}>{'@sarah_chen'}</p>
            </div>
            <p class={styles.Bio}>{'Design Engineer at Acme Inc.'}</p>
          </div>
        </HoverCard.Content>
      </HoverCard.Positioner>
    </Portal>
  </HoverCard.Root>
}

```

### Context

Access the hover card's state with `HoverCard.Context` or the `useHoverCardContext` hook:

**Example: context**

```ripple
import { HoverCard } from 'ark-ripple/hover-card';
import { Portal } from 'ark-ripple/portal';
import { ChevronDown, ChevronUp } from 'lucide-ripple';
import styles from 'styles/hover-card.module.css';

export component Context() {
  const s = 'www';
  <HoverCard.Root>
    <HoverCard.Context>
      <p>
        {'Liked by '}
        <HoverCard.Trigger class={styles.Trigger}>
          component asChild({ propsFn }) {
            <a {...propsFn({ href: '#profile' })}>
              {'@sarah_chen '}
              <HoverCard.Context>
                component children({ context }) {
                  {s}
                  if (@context.open) {
                    <ChevronUp />
                  } else {
                    <ChevronDown />
                  }
                }
              </HoverCard.Context>
            </a>
          }
        </HoverCard.Trigger>
        {' and 3 others'}
      </p>
    </HoverCard.Context>
    <Portal>
      <HoverCard.Positioner>
        <HoverCard.Content class={styles.Content}>
          <HoverCard.Arrow class={styles.Arrow}>
            <HoverCard.ArrowTip class={styles.ArrowTip} />
          </HoverCard.Arrow>
          <div class={styles.Body}>
            <img class={styles.Avatar} src="https://i.pravatar.cc/300?u=sarah" alt="Sarah Chen" />
            <div>
              <p class={styles.Name}>{'Sarah Chen'}</p>
              <p class={styles.Username}>{'@sarah_chen'}</p>
            </div>
            <p class={styles.Bio}>{'Design Engineer at Acme Inc.'}</p>
          </div>
        </HoverCard.Content>
      </HoverCard.Positioner>
    </Portal>
  </HoverCard.Root>
}

```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `closeDelay` | `number` | No | The duration from when the mouse leaves the trigger or content until the hover card closes. |
| `defaultOpen` | `boolean` | No | The initial open state of the hover card when rendered.
Use when you don't need to control the open state of the hover card. |
| `disabled` | `boolean` | No | Whether the hover card is disabled |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{ trigger: string; content: string; positioner: string; arrow: string }>` | No | The ids of the elements in the popover. Useful for composition. |
| `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state |
| `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component |
| `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component |
| `onOpenChange` | `(details: OpenChangeDetails) => void` | No | Function called when the hover card opens or closes. |
| `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component |
| `open` | `boolean` | No | The controlled open state of the hover card |
| `openDelay` | `number` | No | The duration from when the mouse enters the trigger until the hover card opens. |
| `positioning` | `PositioningOptions` | No | The user provided options used to position the popover content |
| `present` | `boolean` | No | Whether the node is present (controlled by the user) |
| `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


**Arrow Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Arrow CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--arrow-size` | The size of the arrow |
| `--arrow-size-half` | Half the size of the arrow |
| `--arrow-background` | Use this variable to style the arrow background |
| `--arrow-offset` | The offset position of the arrow |


**ArrowTip Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | hover-card |
| `[data-part]` | content |
| `[data-state]` | "open" | "closed" |
| `[data-nested]` | popover |
| `[data-has-nested]` | popover |
| `[data-placement]` | The placement of the content |


**Content CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--layer-index` | The index of the dismissable in the layer stack |
| `--nested-layer-count` | The number of nested hover-cards |


**Positioner Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Positioner CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--reference-width` | The width of the reference element |
| `--reference-height` | The height of the root |
| `--available-width` | The available width in viewport |
| `--available-height` | The available height in viewport |
| `--x` | The x position for transform |
| `--y` | The y position for transform |
| `--z-index` | The z-index value |
| `--transform-origin` | The transform origin for animations |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseHoverCardReturn` | Yes |  |
| `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state |
| `present` | `boolean` | No | Whether the node is present (controlled by the user) |
| `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


**Trigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | hover-card |
| `[data-part]` | trigger |
| `[data-placement]` | The placement of the trigger |
| `[data-state]` | "open" | "closed" |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `open` | `boolean` | Whether the hover card is open |
| `setOpen` | `(open: boolean) => void` | Function to open the hover card |
| `reposition` | `(options?: Partial<PositioningOptions>) => void` | Function to reposition the popover |



# Image Cropper 



## Anatomy



```tsx
<ImageCropper.Root>
  <ImageCropper.Viewport>
    <ImageCropper.Image />
    <ImageCropper.Selection>
      <ImageCropper.Handle />
      <ImageCropper.Grid />
    </ImageCropper.Selection>
  </ImageCropper.Viewport>
</ImageCropper.Root>
```

## Examples

### Basic

Set up a basic image cropper. Drag the handles to resize the selection, or drag inside to pan the image.

**Example: basic**

```ripple
import { ImageCropper } from 'ark-ripple/image-cropper';
import styles from 'styles/image-cropper.module.css';

export component Basic() {
  <div class={styles.Layout}>
    <ImageCropper.Root class={styles.Root}>
      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https:/https://ark-ui.rip/images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
        />
        <ImageCropper.Selection class={styles.Selection}>
          for (const position of ImageCropper.handles; key position) {
            <ImageCropper.Handle class={styles.Handle} {position}>
              <div />
            </ImageCropper.Handle>
          }
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.Root>
  </div>
}

```

### Aspect Ratio

Lock the crop area to a specific aspect ratio. Use the `aspectRatio` prop—pass a number like `16/9` for widescreen or
`1` for square.

**Example: aspect-ratio**

```ripple
import { ImageCropper } from 'ark-ripple/image-cropper';
import { RectangleHorizontal, Square, RectangleVertical } from 'lucide-ripple';
import { track } from 'ripple';
import button from 'styles/button.module.css';
import styles from 'styles/image-cropper.module.css';

const aspects = [
  { label: '16:9', value: 16 / 9 },
  { label: '1:1', value: 1 },
  { label: '9:16', value: 9 / 16 },
];

const icons = [RectangleHorizontal, Square, RectangleVertical];

export component AspectRatio() {
  let aspectRatio = track(16 / 9);

  <div class={styles.Layout}>
    <div class={button.Group}>
      for (const aspect of aspects; key aspect.label) {
        <button
          type="button"
          class={button.Root}
          data-variant={@aspectRatio === aspect.value ? 'solid' : undefined}
          onClick={() => {
            @aspectRatio = aspect.value;
          }}
        >
          {aspect.label}
        </button>
      }
    </div>

    <ImageCropper.Root class={styles.Root} {@aspectRatio}>
      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https:/https://ark-ui.rip/images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
        />
        <ImageCropper.Selection class={styles.Selection}>
          for (const position of ImageCropper.handles; key position) {
            <ImageCropper.Handle class={styles.Handle} {position}>
              <div />
            </ImageCropper.Handle>
          }
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.Root>
  </div>
}

```

### Circle Crop

Use `cropShape="circle"` for profile pictures or avatars. The selection becomes a circle instead of a rectangle.

**Example: circle**

```ripple
import { ImageCropper } from 'ark-ripple/image-cropper';
import styles from 'styles/image-cropper.module.css';

export component Circle() {
  <div class={styles.Layout}>
    <ImageCropper.Root class={styles.Root} cropShape="circle">
      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https:/https://ark-ui.rip/images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
        />
        <ImageCropper.Selection class={styles.Selection}>
          for (const position of ImageCropper.handles; key position) {
            <ImageCropper.Handle class={styles.Handle} {position}>
              <div />
            </ImageCropper.Handle>
          }
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.Root>
  </div>
}

```

### Initial Crop

Start with a pre-defined crop area using the `initialCrop` prop. Pass an object with `x`, `y`, `width`, and `height` in
pixels.

**Example: initial-crop**

```ripple
import { ImageCropper } from 'ark-ripple/image-cropper';
import styles from 'styles/image-cropper.module.css';

export component InitialCrop() {
  <div class={styles.Layout}>
    <p class={styles.Description}>{'Starts with a pre-defined crop area'}</p>

    <ImageCropper.Root class={styles.Root} initialCrop={{ x: 50, y: 30, width: 200, height: 120 }}>
      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https:/https://ark-ui.rip/images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
        />
        <ImageCropper.Selection class={styles.Selection}>
          for (const position of ImageCropper.handles; key position) {
            <ImageCropper.Handle class={styles.Handle} {position}>
              <div />
            </ImageCropper.Handle>
          }
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.Root>
  </div>
}

```

### Controlled Zoom

Control zoom programmatically with the `zoom` and `onZoomChange` props. Useful when you want external buttons to zoom in
and out.

**Example: controlled-zoom**

```ripple
import { ImageCropper } from 'ark-ripple/image-cropper';
import { ZoomIn, ZoomOut } from 'lucide-ripple';
import { track } from 'ripple';
import button from 'styles/button.module.css';
import styles from 'styles/image-cropper.module.css';

export component ControlledZoom() {
  let zoom = track(1);

  <div class={styles.Layout}>
    <div class={button.Group}>
      <button
        type="button"
        class={button.Root}
        onClick={() => {
          @zoom = @zoom - 0.1;
        }}
      >
        <ZoomOut />
      </button>
      <span style={{ fontSize: '0.875rem', minWidth: '3rem', textAlign: 'center' }}>
        {@zoom.toFixed(1)}
        {'x'}
      </span>
      <button
        type="button"
        class={button.Root}
        onClick={() => {
          @zoom = @zoom + 0.1;
        }}
      >
        <ZoomIn />
      </button>
    </div>

    <ImageCropper.Root
      class={styles.Root}
      {zoom}
      onZoomChange={(e) => {
        @zoom = e.zoom;
      }}
    >
      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https:/https://ark-ui.rip/images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
        />
        <ImageCropper.Selection class={styles.Selection}>
          for (const position of ImageCropper.handles; key position) {
            <ImageCropper.Handle class={styles.Handle} {position}>
              <div />
            </ImageCropper.Handle>
          }
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.Root>
  </div>
}

```

### Zoom Limits

Set `minZoom` and `maxZoom` to constrain how far users can zoom. Prevents over-zooming or zooming out past the image
bounds.

**Example: zoom-limits**

```ripple
import { ImageCropper } from 'ark-ripple/image-cropper';
import { ZoomIn, ZoomOut } from 'lucide-ripple';
import { track } from 'ripple';
import button from 'styles/button.module.css';
import styles from 'styles/image-cropper.module.css';

export component ZoomLimits() {
  let zoom = track(1);
  const minZoom = 0.5;
  const maxZoom = 2;

  <div class={styles.Layout}>
    <div class={button.Group}>
      <button
        type="button"
        class={button.Root}
        onClick={() => {
          @zoom = Math.max(minZoom, @zoom - 0.1);
        }}
      >
        <ZoomOut />
      </button>
      <span
        style={{ fontSize: '0.875rem', padding: '0 0.5rem', minWidth: '3rem', textAlign: 'center' }}
      >
        {@zoom.toFixed(1)}
        {'x'}
      </span>
      <button
        type="button"
        class={button.Root}
        onClick={() => {
          @zoom = Math.min(maxZoom, @zoom + 0.1);
        }}
      >
        <ZoomIn />
      </button>
    </div>

    <p class={styles.Description}>
      {'Zoom constrained between '}
      {minZoom}
      {'x and '}
      {maxZoom}
      {'x'}
    </p>

    <ImageCropper.Root
      class={styles.Root}
      {zoom}
      onZoomChange={(e) => {
        @zoom = e.zoom;
      }}
      {minZoom}
      {maxZoom}
    >
      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https:/https://ark-ui.rip/images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
        />
        <ImageCropper.Selection class={styles.Selection}>
          for (const position of ImageCropper.handles; key position) {
            <ImageCropper.Handle class={styles.Handle} {position}>
              <div />
            </ImageCropper.Handle>
          }
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.Root>
  </div>
}

```

### Rotation

Rotate the image with the `rotation` and `onRotationChange` props. Values are in degrees—common increments are 90
or 180.

**Example: rotation**

```ripple
import { ImageCropper } from 'ark-ripple/image-cropper';
import { RotateCcw, RotateCw } from 'lucide-ripple';
import { track } from 'ripple';
import button from 'styles/button.module.css';
import styles from 'styles/image-cropper.module.css';

export component Rotation() {
  let rotation = track(0);

  <div class={styles.Layout}>
    <div class={button.Group}>
      <button
        type="button"
        class={button.Root}
        onClick={() => {
          @rotation = @rotation - 90;
        }}
      >
        <RotateCcw />
      </button>
      <button
        type="button"
        class={button.Root}
        onClick={() => {
          @rotation = @rotation + 90;
        }}
      >
        <RotateCw />
      </button>
      <span style={{ fontSize: '0.875rem', padding: '0 0.5rem' }}>
        {@rotation}
        {'°'}
      </span>
    </div>

    <ImageCropper.Root
      class={styles.Root}
      {rotation}
      onRotationChange={(e) => {
        @rotation = e.rotation;
      }}
    >
      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https:/https://ark-ui.rip/images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
        />
        <ImageCropper.Selection class={styles.Selection}>
          for (const position of ImageCropper.handles; key position) {
            <ImageCropper.Handle class={styles.Handle} {position}>
              <div />
            </ImageCropper.Handle>
          }
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.Root>
  </div>
}

```

### Flip

Flip the image horizontally or vertically using the `flip` prop. Pass an object with `horizontal` and `vertical`
booleans.

**Example: flip**

```ripple
import { ImageCropper } from 'ark-ripple/image-cropper';
import { FlipHorizontal, FlipVertical } from 'lucide-ripple';
import { track } from 'ripple';
import button from 'styles/button.module.css';
import styles from 'styles/image-cropper.module.css';

export component Flip() {
  let flip = track({ horizontal: false, vertical: false });

  <div class={styles.Layout}>
    <div class={button.Group}>
      <button
        type="button"
        class={button.Root}
        data-variant={@flip.horizontal ? 'solid' : undefined}
        onClick={() => {
          @flip = { ...@flip, horizontal: !@flip.horizontal };
        }}
      >
        <FlipHorizontal />
        {'Horizontal'}
      </button>
      <button
        type="button"
        class={button.Root}
        data-variant={@flip.vertical ? 'solid' : undefined}
        onClick={() => {
          @flip = { ...@flip, vertical: !@flip.vertical };
        }}
      >
        <FlipVertical />
        {'Vertical'}
      </button>
    </div>

    <ImageCropper.Root
      class={styles.Root}
      {flip}
      onFlipChange={(e) => {
        @flip = e.flip;
      }}
    >
      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https:/https://ark-ui.rip/images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
        />
        <ImageCropper.Selection class={styles.Selection}>
          for (const position of ImageCropper.handles; key position) {
            <ImageCropper.Handle class={styles.Handle} {position}>
              <div />
            </ImageCropper.Handle>
          }
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.Root>
  </div>
}

```

### Min and Max Size

Constrain the crop area size with `minWidth`, `minHeight`, `maxWidth`, and `maxHeight`. Keeps the selection within
sensible bounds.

**Example: min-max-size**

```ripple
import { ImageCropper } from 'ark-ripple/image-cropper';
import styles from 'styles/image-cropper.module.css';

export component MinMaxSize() {
  <div class={styles.Layout}>
    <p class={styles.Description}>{'Crop area constrained to min 80px and max 200px'}</p>

    <ImageCropper.Root
      class={styles.Root}
      minWidth={80}
      minHeight={80}
      maxWidth={200}
      maxHeight={200}
    >
      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https:/https://ark-ui.rip/images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
        />
        <ImageCropper.Selection class={styles.Selection}>
          for (const position of ImageCropper.handles; key position) {
            <ImageCropper.Handle class={styles.Handle} {position}>
              <div />
            </ImageCropper.Handle>
          }
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.Root>
  </div>
}

```

### Fixed Crop Area

Set `fixedCropArea` to `true` when the crop area should stay fixed while the image moves underneath. Useful for
overlay-style cropping.

**Example: fixed**

```ripple
import { ImageCropper } from 'ark-ripple/image-cropper';
import styles from 'styles/image-cropper.module.css';

export component Fixed() {
  <div class={styles.Layout}>
    <ImageCropper.Root class={styles.Root} fixedCropArea>
      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https:/https://ark-ui.rip/images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
        />
        <ImageCropper.Selection class={styles.Selection}>
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.Root>
  </div>
}

```

### Crop Preview

Use `getCroppedImage()` from the context to get the cropped result. Call it with `{ output: 'dataUrl' }` for a base64
string you can use in an `img` src.

**Example: crop-preview**

```ripple
import { ImageCropper, useImageCropper } from 'ark-ripple/image-cropper';
import { Crop } from 'lucide-ripple';
import { track } from 'ripple';
import button from 'styles/button.module.css';
import styles from 'styles/image-cropper.module.css';

export component CropPreview() {
  const imageCropper = useImageCropper();
  let preview = track<string | null>(null);

  const handleCrop = async () => {
    const result = await @imageCropper.getCroppedImage({ output: 'dataUrl' });
    if (typeof result === 'string') {
      @preview = result;
    }
  };

  <div class={styles.Layout}>
    <div class={button.Group}>
      <button type="button" class={button.Root} data-variant="solid" onClick={handleCrop}>
        <Crop />
        {'Crop Image'}
      </button>
    </div>

    <ImageCropper.RootProvider class={styles.Root} value={imageCropper}>
      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https:/https://ark-ui.rip/images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
          crossOrigin="anonymous"
        />
        <ImageCropper.Selection class={styles.Selection}>
          for (const position of ImageCropper.handles; key position) {
            <ImageCropper.Handle class={styles.Handle} {position}>
              <div />
            </ImageCropper.Handle>
          }
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.RootProvider>

    <div class={styles.Preview}>
      <span class={styles.PreviewLabel}>{'Preview'}</span>
      if (@preview) {
        <img src={@preview} alt="Cropped preview" class={styles.PreviewImage} />
      }
    </div>
  </div>
}

```

### Reset

The context exposes a `reset()` method that restores the image to its initial state. Handy for an "undo" or "start over"
button.

**Example: reset**

```ripple
import { ImageCropper, useImageCropper } from 'ark-ripple/image-cropper';
import { FlipHorizontal, RotateCw, RotateCcw, RefreshCw, ZoomIn, ZoomOut } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/image-cropper.module.css';

export component Reset() {
  const imageCropper = useImageCropper();

  <div class={styles.Layout}>
    <div class={button.Group}>
      <button type="button" class={button.Root} onClick={() => @imageCropper.zoomBy(-0.1)}>
        <ZoomOut />
      </button>
      <button type="button" class={button.Root} onClick={() => @imageCropper.zoomBy(0.1)}>
        <ZoomIn />
      </button>
      <button type="button" class={button.Root} onClick={() => @imageCropper.rotateBy(-90)}>
        <RotateCcw />
      </button>
      <button type="button" class={button.Root} onClick={() => @imageCropper.rotateBy(90)}>
        <RotateCw />
      </button>
      <button type="button" class={button.Root} onClick={() => @imageCropper.flipHorizontally()}>
        <FlipHorizontal />
      </button>
      <button
        type="button"
        class={button.Root}
        data-variant="surface"
        onClick={() => @imageCropper.reset()}
      >
        <RefreshCw />
        {'Reset'}
      </button>
    </div>

    <ImageCropper.RootProvider class={styles.Root} value={imageCropper}>
      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https:/https://ark-ui.rip/images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
        />
        <ImageCropper.Selection class={styles.Selection}>
          for (const position of ImageCropper.handles; key position) {
            <ImageCropper.Handle class={styles.Handle} {position}>
              <div />
            </ImageCropper.Handle>
          }
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.RootProvider>
  </div>
}

```

### Events

Listen to `onCropChange` and `onZoomChange` to track crop position and zoom level. Use these to sync with external state
or show live previews.

**Example: events**

```ripple
import { ImageCropper } from 'ark-ripple/image-cropper';
import { track } from 'ripple';
import styles from 'styles/image-cropper.module.css';

export component Events() {
  let cropData = track({ x: 0, y: 0, width: 0, height: 0 });
  let zoom = track(1);

  <div class={styles.Layout}>
    <ImageCropper.Root
      class={styles.Root}
      onCropChange={(e) => {
        @cropData = e.crop;
      }}
      onZoomChange={(e) => {
        @zoom = e.zoom;
      }}
    >
      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https:/https://ark-ui.rip/images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
        />
        <ImageCropper.Selection class={styles.Selection}>
          for (const position of ImageCropper.handles; key position) {
            <ImageCropper.Handle class={styles.Handle} {position}>
              <div />
            </ImageCropper.Handle>
          }
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.Root>

    <div class={styles.DataDisplay}>
      <div class={styles.DataItem}>
        <span class={styles.DataLabel}>{'Zoom'}</span>
        <span class={styles.DataValue}>
          {@zoom.toFixed(2)}
          {'x'}
        </span>
      </div>
      <div class={styles.DataItem}>
        <span class={styles.DataLabel}>{'Position'}</span>
        <span class={styles.DataValue}>
          {Math.round(@cropData.x)}
          {', '}
          {Math.round(@cropData.y)}
        </span>
      </div>
      <div class={styles.DataItem}>
        <span class={styles.DataLabel}>{'Size'}</span>
        <span class={styles.DataValue}>
          {Math.round(@cropData.width)}
          {' × '}
          {Math.round(@cropData.height)}
        </span>
      </div>
    </div>
  </div>
}

```

### Context

Use `ImageCropper.Context` to access the cropper API from anywhere inside the root. You get methods like `zoomBy`,
`rotateBy`, and `setZoom`.

**Example: context**

```ripple
import { ImageCropper } from 'ark-ripple/image-cropper';
import { ZoomIn, ZoomOut } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/image-cropper.module.css';

export component Context() {
  <div class={styles.Layout}>
    <ImageCropper.Root class={styles.Root}>
      <ImageCropper.Context>
        component children({ context }) {
          <div class={button.Group}>
            <button type="button" class={button.Root} onClick={() => @context.zoomBy(-0.1)}>
              <ZoomOut />
            </button>
            <span
              style={{
                fontSize: '0.875rem',
                padding: '0 0.5rem',
                minWidth: '3rem',
                textAlign: 'center',
              }}
            >
              {@context.zoom.toFixed(1)}
              {'x'}
            </span>
            <button type="button" class={button.Root} onClick={() => @context.zoomBy(0.1)}>
              <ZoomIn />
            </button>
          </div>
        }
      </ImageCropper.Context>

      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https:/https://ark-ui.rip/images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
        />
        <ImageCropper.Selection class={styles.Selection}>
          for (const position of ImageCropper.handles; key position) {
            <ImageCropper.Handle class={styles.Handle} {position}>
              <div />
            </ImageCropper.Handle>
          }
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.Root>
  </div>
}

```

### Root Provider

Use `RootProvider` with `useImageCropper` when you need to control the cropper from outside the component tree. Build
custom toolbars or integrate with form state.

**Example: root-provider**

```ripple
import { ImageCropper, useImageCropper } from 'ark-ripple/image-cropper';
import { ZoomIn, ZoomOut } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/image-cropper.module.css';

export component RootProvider() {
  const imageCropper = useImageCropper();

  <div class={styles.Layout}>
    <div class={button.Group}>
      <button
        type="button"
        class={button.Root}
        onClick={() => @imageCropper.setZoom(@imageCropper.zoom - 0.1)}
      >
        <ZoomOut />
      </button>
      <span style={{ fontSize: '0.875rem', minWidth: '3rem', textAlign: 'center' }}>
        {@imageCropper.zoom.toFixed(1)}
        {'x'}
      </span>
      <button
        type="button"
        class={button.Root}
        onClick={() => @imageCropper.setZoom(@imageCropper.zoom + 0.1)}
      >
        <ZoomIn />
      </button>
    </div>

    <ImageCropper.RootProvider class={styles.Root} value={imageCropper}>
      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https:/https://ark-ui.rip/images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
        />
        <ImageCropper.Selection class={styles.Selection}>
          for (const position of ImageCropper.handles; key position) {
            <ImageCropper.Handle class={styles.Handle} {position}>
              <div />
            </ImageCropper.Handle>
          }
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.RootProvider>
  </div>
}

```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `aspectRatio` | `number` | No | The aspect ratio to maintain for the crop area (width / height).
For example, an aspect ratio of 16 / 9 will maintain a width to height ratio of 16:9.
If not provided, the crop area can be freely resized. |
| `cropShape` | `'circle' | 'rectangle'` | No | The shape of the crop area. |
| `defaultFlip` | `FlipState` | No | The initial flip state to apply to the image. |
| `defaultRotation` | `number` | No | The initial rotation to apply to the image in degrees. |
| `defaultZoom` | `number` | No | The initial zoom factor to apply to the image. |
| `fixedCropArea` | `boolean` | No | Whether the crop area is fixed in size and position. |
| `flip` | `FlipState` | No | The controlled flip state of the image. |
| `ids` | `Partial<{
  root: string
  viewport: string
  image: string
  selection: string
  handle: (position: string) => string
}>` | No | The ids of the image cropper elements |
| `initialCrop` | `Rect` | No | The initial rectangle of the crop area.
If not provided, a smart default will be computed based on viewport size and aspect ratio. |
| `maxHeight` | `number` | No | The maximum height of the crop area |
| `maxWidth` | `number` | No | The maximum width of the crop area |
| `maxZoom` | `number` | No | The maximum zoom factor allowed. |
| `minHeight` | `number` | No | The minimum height of the crop area |
| `minWidth` | `number` | No | The minimum width of the crop area |
| `minZoom` | `number` | No | The minimum zoom factor allowed. |
| `nudgeStep` | `number` | No | The base nudge step for keyboard arrow keys (in pixels). |
| `nudgeStepCtrl` | `number` | No | The nudge step when Ctrl/Cmd key is held (in pixels). |
| `nudgeStepShift` | `number` | No | The nudge step when Shift key is held (in pixels). |
| `onCropChange` | `(details: CropChangeDetails) => void` | No | Callback fired when the crop area changes. |
| `onFlipChange` | `(details: FlipChangeDetails) => void` | No | Callback fired when the flip state changes. |
| `onRotationChange` | `(details: RotationChangeDetails) => void` | No | Callback fired when the rotation changes. |
| `onZoomChange` | `(details: ZoomChangeDetails) => void` | No | Callback fired when the zoom level changes. |
| `rotation` | `number` | No | The controlled rotation of the image in degrees (0 - 360). |
| `translations` | `IntlTranslations` | No | Specifies the localized strings that identify accessibility elements and their states. |
| `zoom` | `number` | No | The controlled zoom level of the image. |
| `zoomSensitivity` | `number` | No | Controls how responsive pinch-to-zoom is. |
| `zoomStep` | `number` | No | The amount of zoom applied per wheel step. |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | image-cropper |
| `[data-part]` | root |
| `[data-fixed]` |  |
| `[data-shape]` |  |
| `[data-pinch]` |  |
| `[data-dragging]` | Present when in the dragging state |
| `[data-panning]` |  |


**Root CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--crop-width` | The width of the Root |
| `--crop-height` | The height of the Root |
| `--crop-x` | The crop x value for the Root |
| `--crop-y` | The crop y value for the Root |
| `--image-zoom` | The image zoom value for the Root |
| `--image-rotation` | The image rotation value for the Root |
| `--image-offset-x` | The offset position for image |
| `--image-offset-y` | The offset position for image |


**Grid Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `axis` | `'horizontal' | 'vertical'` | Yes | The axis of the grid lines to display |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Grid Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | image-cropper |
| `[data-part]` | grid |
| `[data-axis]` | The axis to resize |
| `[data-dragging]` | Present when in the dragging state |
| `[data-panning]` |  |


**Handle Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `position` | `HandlePosition` | Yes | The position of the handle |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Handle Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | image-cropper |
| `[data-part]` | handle |
| `[data-position]` |  |
| `[data-disabled]` | Present when disabled |


**Image Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Image Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | image-cropper |
| `[data-part]` | image |
| `[data-ready]` |  |
| `[data-flip-horizontal]` |  |
| `[data-flip-vertical]` |  |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseImageCropperReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Selection Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Selection Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | image-cropper |
| `[data-part]` | selection |
| `[data-disabled]` | Present when disabled |
| `[data-shape]` |  |
| `[data-measured]` |  |
| `[data-dragging]` | Present when in the dragging state |
| `[data-panning]` |  |


**Viewport Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Viewport Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | image-cropper |
| `[data-part]` | viewport |
| `[data-disabled]` | Present when disabled |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `zoom` | `number` | The current zoom level of the image. |
| `rotation` | `number` | The current rotation of the image in degrees. |
| `flip` | `FlipState` | The current flip state of the image. |
| `crop` | `Rect` | The current crop area rectangle in viewport coordinates. |
| `offset` | `Point` | The current offset (pan position) of the image. |
| `naturalSize` | `Size` | The natural (original) size of the image. |
| `viewportRect` | `BoundingRect` | The viewport rectangle dimensions and position. |
| `dragging` | `boolean` | Whether the crop area is currently being dragged. |
| `panning` | `boolean` | Whether the image is currently being panned. |
| `setZoom` | `(zoom: number) => void` | Function to set the zoom level of the image. |
| `zoomBy` | `(delta: number) => void` | Function to zoom the image by a relative amount. |
| `setRotation` | `(rotation: number) => void` | Function to set the rotation of the image. |
| `rotateBy` | `(degrees: number) => void` | Function to rotate the image by a relative amount in degrees. |
| `setFlip` | `(flip: Partial<FlipState>) => void` | Function to set the flip state of the image. |
| `flipHorizontally` | `(value?: boolean) => void` | Function to flip the image horizontally. Pass a boolean to set explicitly or omit to toggle. |
| `flipVertically` | `(value?: boolean) => void` | Function to flip the image vertically. Pass a boolean to set explicitly or omit to toggle. |
| `resize` | `(handlePosition: HandlePosition, delta: number) => void` | Function to resize the crop area from a handle programmatically. |
| `reset` | `() => void` | Function to reset the cropper to its initial state. |
| `getCroppedImage` | `(options?: GetCroppedImageOptions) => Promise<string | Blob>` | Function to get the cropped image with all transformations applied.
Returns a Promise that resolves to either a Blob or data URL. |
| `getCropData` | `() => CropData` | Function to get the crop data in natural image pixel coordinates.
These coordinates are relative to the original image dimensions,
accounting for zoom, rotation, and flip transformations.
Use this for server-side cropping or state persistence. |



# Listbox 



## Anatomy

{/*  */}

```tsx
<Listbox.Root>
  <Listbox.Label />
  <Listbox.Content>
    <Listbox.ItemGroup>
      <Listbox.ItemGroupLabel />
      <Listbox.Item>
        <Listbox.ItemText />
        <Listbox.ItemIndicator />
      </Listbox.Item>
    </Listbox.ItemGroup>
  </Listbox.Content>
  <Listbox.ValueText />
</Listbox.Root>
```

## Examples

### Basic

Here's a basic example of the Listbox component.

**Example: basic**

```ripple
import { Listbox, createListCollection } from 'ark-ripple/listbox';
import { Check } from 'lucide-ripple';
import styles from 'styles/listbox.module.css';

export component Basic() {
  const collection = createListCollection(
    {
      items: [
        { label: 'United States', value: 'us' },
        { label: 'United Kingdom', value: 'uk' },
        { label: 'Canada', value: 'ca' },
        { label: 'Australia', value: 'au' },
        { label: 'Germany', value: 'de' },
        { label: 'France', value: 'fr' },
        { label: 'Japan', value: 'jp' },
      ],
    },
  );

  <Listbox.Root class={styles.Root} {collection}>
    <Listbox.Label class={styles.Label}>{'Select Country'}</Listbox.Label>
    <Listbox.Content class={styles.Content}>
      for (const item of collection.items; key item.value) {
        <Listbox.Item class={styles.Item} {item}>
          <Listbox.ItemText class={styles.ItemText}>{item.label}</Listbox.ItemText>
          <Listbox.ItemIndicator class={styles.ItemIndicator}>
            <Check />
          </Listbox.ItemIndicator>
        </Listbox.Item>
      }
    </Listbox.Content>
  </Listbox.Root>
}

```

### Controlled

The Listbox component can be controlled by using the `value` and `onValueChange` props. This allows you to manage the
selected value externally.

**Example: controlled**

```ripple
import { Listbox, createListCollection } from 'ark-ripple/listbox';
import { Check } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/listbox.module.css';

export component Controlled() {
  const collection = createListCollection(
    {
      items: [
        { label: 'Small', value: 'sm' },
        { label: 'Medium', value: 'md' },
        { label: 'Large', value: 'lg' },
        { label: 'Extra Large', value: 'xl' },
      ],
    },
  );

  let value = track(['md']);

  <Listbox.Root
    class={styles.Root}
    {collection}
    {value}
    onValueChange={(e) => {
      @value = e.value;
    }}
  >
    <Listbox.Label class={styles.Label}>{'Select Size'}</Listbox.Label>
    <Listbox.Content class={styles.Content}>
      for (const item of collection.items; key item.value) {
        <Listbox.Item class={styles.Item} {item}>
          <Listbox.ItemText class={styles.ItemText}>{item.label}</Listbox.ItemText>
          <Listbox.ItemIndicator class={styles.ItemIndicator}>
            <Check />
          </Listbox.ItemIndicator>
        </Listbox.Item>
      }
    </Listbox.Content>
  </Listbox.Root>
}

```

### Root Provider

An alternative way to control the listbox is to use the `RootProvider` component and the `useListbox` hook. This way you
can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { Listbox, createListCollection, useListbox } from 'ark-ripple/listbox';
import { Check } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/listbox.module.css';

export component RootProvider() {
  const collection = createListCollection(
    {
      items: [
        { label: 'Low', value: 'low' },
        { label: 'Medium', value: 'medium' },
        { label: 'High', value: 'high' },
        { label: 'Critical', value: 'critical' },
      ],
    },
  );

  const listbox = useListbox({ collection });

  <div class="stack">
    <button
      type="button"
      class={button.Root}
      onClick={() => {
        @listbox.setValue(['high']);
      }}
    >
      {'Set to High'}
    </button>
    <Listbox.RootProvider class={styles.Root} value={listbox}>
      <Listbox.Label class={styles.Label}>{'Select Priority'}</Listbox.Label>
      <Listbox.Content class={styles.Content}>
        for (const item of collection.items; key item.value) {
          <Listbox.Item class={styles.Item} {item}>
            <Listbox.ItemText class={styles.ItemText}>{item.label}</Listbox.ItemText>
            <Listbox.ItemIndicator class={styles.ItemIndicator}>
              <Check />
            </Listbox.ItemIndicator>
          </Listbox.Item>
        }
      </Listbox.Content>
    </Listbox.RootProvider>
  </div>
}

```

### Disabled Item

Listbox items can be disabled using the `disabled` prop on the collection item.

**Example: disabled-item**

```ripple
import { Listbox, createListCollection } from 'ark-ripple/listbox';
import { Check } from 'lucide-ripple';
import styles from 'styles/listbox.module.css';

export component DisabledItem() {
  const collection = createListCollection(
    {
      items: [
        { label: 'Free', value: 'free' },
        { label: 'Pro', value: 'pro' },
        { label: 'Enterprise', value: 'enterprise', disabled: true },
        { label: 'Custom', value: 'custom' },
      ],
    },
  );

  <Listbox.Root class={styles.Root} {collection}>
    <Listbox.Label class={styles.Label}>{'Select Plan'}</Listbox.Label>
    <Listbox.Content class={styles.Content}>
      for (const item of collection.items; key item.value) {
        <Listbox.Item class={styles.Item} {item}>
          <Listbox.ItemText class={styles.ItemText}>{item.label}</Listbox.ItemText>
          <Listbox.ItemIndicator class={styles.ItemIndicator}>
            <Check />
          </Listbox.ItemIndicator>
        </Listbox.Item>
      }
    </Listbox.Content>
  </Listbox.Root>
}

```

> You can also use the `isItemDisabled` within the `createListCollection` to disable items based on a condition.

### Multiple

You can set the `selectionMode` property as `multiple` to allow the user to select multiple items at a time.

**Example: multiple**

```ripple
import { Listbox, createListCollection } from 'ark-ripple/listbox';
import { Check } from 'lucide-ripple';
import styles from 'styles/listbox.module.css';

export component Multiple() {
  const collection = createListCollection(
    {
      items: [
        { label: 'Monday', value: 'mon' },
        { label: 'Tuesday', value: 'tue' },
        { label: 'Wednesday', value: 'wed' },
        { label: 'Thursday', value: 'thu' },
        { label: 'Friday', value: 'fri' },
        { label: 'Saturday', value: 'sat' },
        { label: 'Sunday', value: 'sun' },
      ],
    },
  );

  <Listbox.Root class={styles.Root} {collection} selectionMode="multiple">
    <Listbox.Label class={styles.Label}>{'Select Days'}</Listbox.Label>
    <Listbox.Content class={styles.Content}>
      for (const item of collection.items; key item.value) {
        <Listbox.Item class={styles.Item} {item}>
          <Listbox.ItemText class={styles.ItemText}>{item.label}</Listbox.ItemText>
          <Listbox.ItemIndicator class={styles.ItemIndicator}>
            <Check />
          </Listbox.ItemIndicator>
        </Listbox.Item>
      }
    </Listbox.Content>
  </Listbox.Root>
}

```

### Grouping

The Listbox component supports grouping items. You can use the `groupBy` function to group items based on a specific
property.

**Example: group**

```ripple
import { Listbox, createListCollection } from 'ark-ripple/listbox';
import { Check } from 'lucide-ripple';
import styles from 'styles/listbox.module.css';

export component Group() {
  const collection = createListCollection(
    {
      items: [
        { label: 'New York', value: 'nyc', region: 'North America' },
        { label: 'Los Angeles', value: 'lax', region: 'North America' },
        { label: 'Toronto', value: 'yyz', region: 'North America' },
        { label: 'London', value: 'lhr', region: 'Europe' },
        { label: 'Paris', value: 'cdg', region: 'Europe' },
        { label: 'Berlin', value: 'ber', region: 'Europe' },
        { label: 'Tokyo', value: 'nrt', region: 'Asia Pacific' },
        { label: 'Singapore', value: 'sin', region: 'Asia Pacific' },
        { label: 'Sydney', value: 'syd', region: 'Asia Pacific' },
      ],
      groupBy: (item) => item.region,
    },
  );

  <Listbox.Root class={styles.Root} {collection}>
    <Listbox.Label class={styles.Label}>{'Select Region'}</Listbox.Label>
    <Listbox.Content class={styles.Content}>
      for (const [region, items] of collection.group(); key region) {
        <Listbox.ItemGroup class={styles.ItemGroup}>
          <Listbox.ItemGroupLabel class={styles.ItemGroupLabel}>{region}</Listbox.ItemGroupLabel>
          for (const item of items; key item.value) {
            <Listbox.Item class={styles.Item} {item}>
              <Listbox.ItemText class={styles.ItemText}>{item.label}</Listbox.ItemText>
              <Listbox.ItemIndicator class={styles.ItemIndicator}>
                <Check />
              </Listbox.ItemIndicator>
            </Listbox.Item>
          }
        </Listbox.ItemGroup>
      }
    </Listbox.Content>
  </Listbox.Root>
}

```

### Extended Selection

The extended selection mode allows users to select multiple items using keyboard modifiers like `Cmd` (Mac) or `Ctrl`
(Windows/Linux).

**Example: extended-select**

```ripple
import { Listbox, createListCollection } from 'ark-ripple/listbox';
import { Check } from 'lucide-ripple';
import styles from 'styles/listbox.module.css';

export component ExtendedSelect() {
  const collection = createListCollection(
    {
      items: [
        { label: 'React', value: 'react' },
        { label: 'Vue', value: 'vue' },
        { label: 'Angular', value: 'angular' },
        { label: 'Svelte', value: 'svelte' },
        { label: 'Solid', value: 'solid' },
        { label: 'Preact', value: 'preact' },
      ],
    },
  );

  <Listbox.Root class={styles.Root} {collection} selectionMode="extended">
    <Listbox.Label class={styles.Label}>
      {'Hold '}
      <kbd>{'⌘'}</kbd>
      {' or '}
      <kbd>{'Ctrl'}</kbd>
      {' to select multiple'}
    </Listbox.Label>
    <Listbox.Content class={styles.Content}>
      for (const item of collection.items; key item.value) {
        <Listbox.Item class={styles.Item} {item}>
          <Listbox.ItemText class={styles.ItemText}>{item.label}</Listbox.ItemText>
          <Listbox.ItemIndicator class={styles.ItemIndicator}>
            <Check />
          </Listbox.ItemIndicator>
        </Listbox.Item>
      }
    </Listbox.Content>
  </Listbox.Root>
}

```

### Horizontal

Use the `orientation` prop to display the listbox items horizontally.

**Example: horizontal**

```ripple
import { Listbox, createListCollection } from 'ark-ripple/listbox';
import { Check } from 'lucide-ripple';
import styles from 'styles/listbox.module.css';

export component Horizontal() {
  const collection = createListCollection(
    {
      items: [
        {
          title: 'Midnight Dreams',
          artist: 'Luna Ray',
          image: 'https://picsum.photos/seed/album1/300/300',
        },
        {
          title: 'Neon Skyline',
          artist: 'The Electric',
          image: 'https://picsum.photos/seed/album2/300/300',
        },
        {
          title: 'Acoustic Sessions',
          artist: 'Sarah Woods',
          image: 'https://picsum.photos/seed/album3/300/300',
        },
        {
          title: 'Urban Echoes',
          artist: 'Metro Collective',
          image: 'https://picsum.photos/seed/album4/300/300',
        },
        {
          title: 'Summer Vibes',
          artist: 'Coastal Waves',
          image: 'https://picsum.photos/seed/album5/300/300',
        },
      ],
      itemToValue: (item) => item.title,
      itemToString: (item) => item.title,
    },
  );

  <Listbox.Root class={styles.Root} {collection} orientation="horizontal">
    <Listbox.Label class={styles.Label}>{'Select Album'}</Listbox.Label>
    <Listbox.Content class={styles.Content}>
      for (const item of collection.items; key item.title) {
        <Listbox.Item class={styles.ItemCard} {item}>
          <Listbox.ItemIndicator class={styles.ItemCardIndicator}>
            <Check />
          </Listbox.ItemIndicator>
          <img class={styles.ItemCardImage} src={item.image} alt={item.title} />
          <span class={styles.ItemCardTitle}>{item.title}</span>
          <span class={styles.ItemCardArtist}>{item.artist}</span>
        </Listbox.Item>
      }
    </Listbox.Content>
  </Listbox.Root>
}

```

### Grid Layout

Use `createGridCollection` to display items in a grid layout with keyboard navigation support.

**Example: grid**

```ripple
import { createGridCollection } from 'ark-ripple/collection';
import { Listbox } from 'ark-ripple/listbox';
import styles from 'styles/listbox.module.css';

export component Grid() {
  const collection = createGridCollection(
    {
      items: [
        { label: '😀', value: 'grinning' },
        { label: '😍', value: 'heart-eyes' },
        { label: '🥳', value: 'partying' },
        { label: '😎', value: 'sunglasses' },
        { label: '🤩', value: 'star-struck' },
        { label: '😂', value: 'joy' },
        { label: '🥰', value: 'smiling-hearts' },
        { label: '😊', value: 'blush' },
        { label: '🤗', value: 'hugging' },
        { label: '😇', value: 'innocent' },
        { label: '🔥', value: 'fire' },
        { label: '✨', value: 'sparkles' },
        { label: '💯', value: 'hundred' },
        { label: '🎉', value: 'tada' },
        { label: '❤️', value: 'heart' },
        { label: '👍', value: 'thumbs-up' },
        { label: '👏', value: 'clap' },
        { label: '🚀', value: 'rocket' },
        { label: '⭐', value: 'star' },
        { label: '🌈', value: 'rainbow' },
      ],
      columnCount: 5,
    },
  );

  <Listbox.Root class={styles.Root} {collection}>
    <Listbox.Label class={styles.Label}>{'Pick a reaction'}</Listbox.Label>
    <Listbox.Content class={styles.GridContent}>
      for (const item of collection.items; key item.value) {
        <Listbox.Item class={styles.GridItem} {item}>
          <Listbox.ItemText>{item.label}</Listbox.ItemText>
        </Listbox.Item>
      }
    </Listbox.Content>
  </Listbox.Root>
}

```

### Filtering

Use `useListCollection` with the `filter` function to enable filtering of items.

**Example: filtering**

```ripple
import { useListCollection } from 'ark-ripple/collection';
import { Listbox } from 'ark-ripple/listbox';
import { Check } from 'lucide-ripple';
import field from 'styles/field.module.css';
import styles from 'styles/listbox.module.css';

export component Filtering() {
  const { collection, filter } = useListCollection(
    {
      initialItems: [
        { label: 'React', value: 'react' },
        { label: 'Vue', value: 'vue' },
        { label: 'Angular', value: 'angular' },
        { label: 'Svelte', value: 'svelte' },
        { label: 'Solid', value: 'solid' },
        { label: 'Next.js', value: 'nextjs' },
        { label: 'Nuxt.js', value: 'nuxtjs' },
        { label: 'Remix', value: 'remix' },
        { label: 'Gatsby', value: 'gatsby' },
        { label: 'Preact', value: 'preact' },
      ],
      filter: (itemText, filterText) => itemText.toLowerCase().includes(filterText.toLowerCase()),
    },
  );

  <Listbox.Root class={styles.Root} {collection}>
    <Listbox.Label class={styles.Label}>{'Select Framework'}</Listbox.Label>
    <Listbox.Input
      class={field.Input}
      placeholder="Search frameworks..."
      onInput={(e: Event) => filter((e.target as HTMLInputElement).value)}
    />
    <Listbox.Content class={styles.Content}>
      for (const item of @collection.items; key item.value) {
        <Listbox.Item class={styles.Item} {item}>
          <Listbox.ItemText class={styles.ItemText}>{item.label}</Listbox.ItemText>
          <Listbox.ItemIndicator class={styles.ItemIndicator}>
            <Check />
          </Listbox.ItemIndicator>
        </Listbox.Item>
      }
      <Listbox.Empty class={styles.Empty}>{'No frameworks found'}</Listbox.Empty>
    </Listbox.Content>
  </Listbox.Root>
}

```

### Select All

Use `useListboxContext` to implement a "Select All" functionality that allows users to select or deselect all items at
once.

**Example: select-all**

```ripple
import { Listbox, createListCollection, useListboxContext } from 'ark-ripple/listbox';
import { Check, Minus } from 'lucide-ripple';
import styles from 'styles/listbox.module.css';

const frameworks = createListCollection(
  {
    items: [
      { label: 'React', value: 'react' },
      { label: 'Vue', value: 'vue' },
      { label: 'Angular', value: 'angular' },
      { label: 'Svelte', value: 'svelte' },
      { label: 'Next.js', value: 'nextjs' },
      { label: 'Nuxt.js', value: 'nuxtjs' },
      { label: 'Remix', value: 'remix' },
      { label: 'Gatsby', value: 'gatsby' },
    ],
  },
);

component SelectAllHeader() {
  const listbox = useListboxContext();
  const isAllSelected = @listbox.value.length === frameworks.items.length;
  const isSomeSelected =
    @listbox.value.length > 0 && @listbox.value.length < frameworks.items.length;

  const handleSelectAll = () => {
    if (isAllSelected) {
      @listbox.setValue([]);
    } else {
      @listbox.setValue(frameworks.items.map((item) => item.value));
    }
  };

  <button class={styles.SelectAllHeader} type="button" onClick={handleSelectAll}>
    <span class={styles.SelectAllHeaderIndicator}>
      if (isAllSelected) {
        <Check />
      } else if (isSomeSelected) {
        <Minus />
      }
    </span>
    <span class={styles.Label}>{'Select All'}</span>
  </button>
}

export component SelectAll() {
  <Listbox.Root class={styles.Root} collection={frameworks} selectionMode="multiple">
    <SelectAllHeader />
    <Listbox.Content class={styles.Content}>
      for (const item of frameworks.items; key item.value) {
        <Listbox.Item class={styles.Item} {item}>
          <Listbox.ItemText class={styles.ItemText}>{item.label}</Listbox.ItemText>
          <Listbox.ItemIndicator class={styles.ItemIndicator}>
            <Check />
          </Listbox.ItemIndicator>
        </Listbox.Item>
      }
    </Listbox.Content>
  </Listbox.Root>
}

```

### Value Text

Use `Listbox.ValueText` to display the selected values as a comma-separated string.

**Example: value-text**

```ripple
import { Listbox, createListCollection } from 'ark-ripple/listbox';
import { Check } from 'lucide-ripple';
import styles from 'styles/listbox.module.css';

export component ValueText() {
  const collection = createListCollection(
    {
      items: [
        { label: 'Red', value: 'red' },
        { label: 'Blue', value: 'blue' },
        { label: 'Green', value: 'green' },
        { label: 'Yellow', value: 'yellow' },
        { label: 'Purple', value: 'purple' },
      ],
    },
  );

  <Listbox.Root
    class={styles.Root}
    {collection}
    selectionMode="multiple"
    defaultValue={['red', 'blue']}
  >
    <Listbox.Label class={styles.Label}>
      {'Colors: '}
      <Listbox.ValueText class={styles.ValueText} />
    </Listbox.Label>
    <Listbox.Content class={styles.Content}>
      for (const item of collection.items; key item.value) {
        <Listbox.Item class={styles.Item} {item}>
          <Listbox.ItemText class={styles.ItemText}>{item.label}</Listbox.ItemText>
          <Listbox.ItemIndicator class={styles.ItemIndicator}>
            <Check />
          </Listbox.ItemIndicator>
        </Listbox.Item>
      }
    </Listbox.Content>
  </Listbox.Root>
}

```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `collection` | `ListCollection<T>` | Yes | The collection of items |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `defaultHighlightedValue` | `string` | No | The initial value of the highlighted item when opened.
Use when you don't need to control the highlighted value of the listbox. |
| `defaultValue` | `string[]` | No | The initial default value of the listbox when rendered.
Use when you don't need to control the value of the listbox. |
| `deselectable` | `boolean` | No | Whether to disallow empty selection |
| `disabled` | `boolean` | No | Whether the listbox is disabled |
| `disallowSelectAll` | `boolean` | No | Whether to disallow selecting all items when `meta+a` is pressed |
| `highlightedValue` | `string` | No | The controlled key of the highlighted item |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{
  root: string
  content: string
  label: string
  item: (id: string | number) => string
  itemGroup: (id: string | number) => string
  itemGroupLabel: (id: string | number) => string
}>` | No | The ids of the elements in the listbox. Useful for composition. |
| `loopFocus` | `boolean` | No | Whether to loop the keyboard navigation through the options |
| `onHighlightChange` | `(details: HighlightChangeDetails<T>) => void` | No | The callback fired when the highlighted item changes. |
| `onSelect` | `(details: SelectionDetails) => void` | No | Function called when an item is selected |
| `onValueChange` | `(details: ValueChangeDetails<T>) => void` | No | The callback fired when the selected item changes. |
| `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the listbox. |
| `scrollToIndexFn` | `(details: ScrollToIndexDetails) => void` | No | Function to scroll to a specific index |
| `selectionMode` | `SelectionMode` | No | How multiple selection should behave in the listbox.

- `single`: The user can select a single item.
- `multiple`: The user can select multiple items without using modifier keys.
- `extended`: The user can select multiple items by using modifier keys. |
| `selectOnHighlight` | `boolean` | No | Whether to select the item when it is highlighted |
| `typeahead` | `boolean` | No | Whether to enable typeahead on the listbox |
| `value` | `string[]` | No | The controlled keys of the selected items |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | listbox |
| `[data-part]` | root |
| `[data-orientation]` | The orientation of the listbox |
| `[data-disabled]` | Present when disabled |


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | listbox |
| `[data-part]` | content |
| `[data-activedescendant]` | The id the active descendant of the content |
| `[data-orientation]` | The orientation of the content |
| `[data-layout]` |  |
| `[data-empty]` | Present when the content is empty |


**Content CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--column-count` | The column count value for the Content |


**Empty Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Input Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `autoHighlight` | `boolean` | No | Whether to automatically highlight the item when typing |


**Input Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | listbox |
| `[data-part]` | input |
| `[data-disabled]` | Present when disabled |


**ItemGroupLabel Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemGroup Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemGroup Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | listbox |
| `[data-part]` | item-group |
| `[data-disabled]` | Present when disabled |
| `[data-orientation]` | The orientation of the item |
| `[data-empty]` | Present when the content is empty |


**ItemIndicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemIndicator Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | listbox |
| `[data-part]` | item-indicator |
| `[data-state]` | "checked" | "unchecked" |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `highlightOnHover` | `boolean` | No | Whether to highlight the item on hover |
| `item` | `any` | No | The item to render |


**Item Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | listbox |
| `[data-part]` | item |
| `[data-value]` | The value of the item |
| `[data-selected]` | Present when selected |
| `[data-layout]` |  |
| `[data-state]` | "checked" | "unchecked" |
| `[data-orientation]` | The orientation of the item |
| `[data-highlighted]` | Present when highlighted |
| `[data-disabled]` | Present when disabled |


**ItemText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemText Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | listbox |
| `[data-part]` | item-text |
| `[data-state]` | "checked" | "unchecked" |
| `[data-disabled]` | Present when disabled |
| `[data-highlighted]` | Present when highlighted |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | listbox |
| `[data-part]` | label |
| `[data-disabled]` | Present when disabled |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseListboxReturn<T>` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ValueText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `placeholder` | `string` | No | Text to display when no value is listboxed. |


**ValueText Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | listbox |
| `[data-part]` | value-text |
| `[data-disabled]` | Present when disabled |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `empty` | `boolean` | Whether the select value is empty |
| `highlightedValue` | `string` | The value of the highlighted item |
| `highlightedItem` | `V` | The highlighted item |
| `highlightValue` | `(value: string) => void` | Function to highlight a value |
| `clearHighlightedValue` | `VoidFunction` | Function to clear the highlighted value |
| `selectedItems` | `V[]` | The selected items |
| `hasSelectedItems` | `boolean` | Whether there's a selected option |
| `value` | `string[]` | The selected item keys |
| `valueAsString` | `string` | The string representation of the selected items |
| `selectValue` | `(value: string) => void` | Function to select a value |
| `selectAll` | `VoidFunction` | Function to select all values.

**Note**: This should only be called when the selectionMode is `multiple` or `extended`.
Otherwise, an exception will be thrown. |
| `setValue` | `(value: string[]) => void` | Function to set the value of the select |
| `clearValue` | `(value?: string) => void` | Function to clear the value of the select.
If a value is provided, it will only clear that value, otherwise, it will clear all values. |
| `getItemState` | `(props: ItemProps<any>) => ItemState` | Returns the state of a select item |
| `collection` | `ListCollection<V>` | Function to toggle the select |
| `disabled` | `boolean` | Whether the select is disabled |



# Marquee 



## Anatomy

{/*  */}

```tsx
<Marquee.Root>
  <Marquee.Edge />
  <Marquee.Viewport>
    <Marquee.Content>
      <Marquee.Item />
    </Marquee.Content>
  </Marquee.Viewport>
</Marquee.Root>
```

## Examples

**Example: basic**

```ripple
import { Marquee } from 'ark-ripple/marquee';
import styles from 'styles/marquee.module.css';

const items = [
  { name: 'Apple', logo: '🍎' },
  { name: 'Banana', logo: '🍌' },
  { name: 'Cherry', logo: '🍒' },
  { name: 'Grape', logo: '🍇' },
  { name: 'Watermelon', logo: '🍉' },
  { name: 'Strawberry', logo: '🍓' },
];

export component Basic() {
  <Marquee.Root class={styles.Root}>
    <Marquee.Viewport class={styles.Viewport}>
      <Marquee.Content class={styles.Content}>
        for (const item of items; key item.name) {
          <Marquee.Item class={styles.Item}>
            <span class={styles.ItemLogo}>{item.logo}</span>
            <span class={styles.ItemName}>{item.name}</span>
          </Marquee.Item>
        }
      </Marquee.Content>
    </Marquee.Viewport>
  </Marquee.Root>
}

```

### Auto Fill

Use the `autoFill` prop to automatically duplicate content to fill the viewport. The `spacing` prop controls the gap
between duplicated content instances:

**Example: auto-fill**

```ripple
import { Marquee } from 'ark-ripple/marquee';
import styles from 'styles/marquee.module.css';

const items = [
  { name: 'Apple', logo: '🍎' },
  { name: 'Banana', logo: '🍌' },
  { name: 'Cherry', logo: '🍒' },
];

export component AutoFill() {
  <Marquee.Root autoFill spacing="2rem" class={styles.Root}>
    <Marquee.Viewport class={styles.Viewport}>
      <Marquee.Content class={styles.Content}>
        for (const item of items; key item.name) {
          <Marquee.Item class={styles.Item}>
            <span class={styles.ItemLogo}>{item.logo}</span>
            <span class={styles.ItemName}>{item.name}</span>
          </Marquee.Item>
        }
      </Marquee.Content>
    </Marquee.Viewport>
  </Marquee.Root>
}

```

### Reverse

Set the `reverse` prop to reverse the scroll direction:

**Example: reverse**

```ripple
import { Marquee } from 'ark-ripple/marquee';
import styles from 'styles/marquee.module.css';

const items = [
  { name: 'Apple', logo: '🍎' },
  { name: 'Banana', logo: '🍌' },
  { name: 'Cherry', logo: '🍒' },
  { name: 'Grape', logo: '🍇' },
  { name: 'Watermelon', logo: '🍉' },
  { name: 'Strawberry', logo: '🍓' },
];

export component Reverse() {
  <Marquee.Root reverse class={styles.Root}>
    <Marquee.Viewport class={styles.Viewport}>
      <Marquee.Content class={styles.Content}>
        for (const item of items; key item.name) {
          <Marquee.Item class={styles.Item}>
            <span class={styles.ItemLogo}>{item.logo}</span>
            <span class={styles.ItemName}>{item.name}</span>
          </Marquee.Item>
        }
      </Marquee.Content>
    </Marquee.Viewport>
  </Marquee.Root>
}

```

### Vertical

Set `side="bottom"` (or `side="top"`) to create a vertical marquee:

**Example: vertical**

```ripple
import { Marquee } from 'ark-ripple/marquee';
import styles from 'styles/marquee.module.css';

const items = [
  { name: 'Apple', logo: '🍎' },
  { name: 'Banana', logo: '🍌' },
  { name: 'Cherry', logo: '🍒' },
  { name: 'Grape', logo: '🍇' },
  { name: 'Watermelon', logo: '🍉' },
  { name: 'Strawberry', logo: '🍓' },
];

export component Vertical() {
  <Marquee.Root side="bottom" class={styles.Root}>
    <Marquee.Viewport class={styles.Viewport}>
      <Marquee.Content class={styles.Content}>
        for (const item of items; key item.name) {
          <Marquee.Item class={styles.Item}>
            <span class={styles.ItemLogo}>{item.logo}</span>
            <span class={styles.ItemName}>{item.name}</span>
          </Marquee.Item>
        }
      </Marquee.Content>
    </Marquee.Viewport>
  </Marquee.Root>
}

```

### Speed

Control the animation speed using the `speed` prop, which accepts values in pixels per second:

**Example: speed**

```ripple
import { Marquee } from 'ark-ripple/marquee';
import styles from 'styles/marquee.module.css';

const items = [
  { name: 'Apple', logo: '🍎' },
  { name: 'Banana', logo: '🍌' },
  { name: 'Cherry', logo: '🍒' },
  { name: 'Grape', logo: '🍇' },
  { name: 'Watermelon', logo: '🍉' },
  { name: 'Strawberry', logo: '🍓' },
];

export component Speed() {
  <div class="stack">
    <div>
      <h3>{'Slow (25px/s)'}</h3>
      <Marquee.Root speed={25} class={styles.Root}>
        <Marquee.Viewport class={styles.Viewport}>
          <Marquee.Content class={styles.Content}>
            for (const item of items; key item.name) {
              <Marquee.Item class={styles.Item}>
                <span class={styles.ItemLogo}>{item.logo}</span>
                <span class={styles.ItemName}>{item.name}</span>
              </Marquee.Item>
            }
          </Marquee.Content>
        </Marquee.Viewport>
      </Marquee.Root>
    </div>

    <div>
      <h3>{'Normal (50px/s)'}</h3>
      <Marquee.Root speed={50} class={styles.Root}>
        <Marquee.Viewport class={styles.Viewport}>
          <Marquee.Content class={styles.Content}>
            for (const item of items; key item.name) {
              <Marquee.Item class={styles.Item}>
                <span class={styles.ItemLogo}>{item.logo}</span>
                <span class={styles.ItemName}>{item.name}</span>
              </Marquee.Item>
            }
          </Marquee.Content>
        </Marquee.Viewport>
      </Marquee.Root>
    </div>

    <div>
      <h3>{'Fast (100px/s)'}</h3>
      <Marquee.Root speed={100} class={styles.Root}>
        <Marquee.Viewport class={styles.Viewport}>
          <Marquee.Content class={styles.Content}>
            for (const item of items; key item.name) {
              <Marquee.Item class={styles.Item}>
                <span class={styles.ItemLogo}>{item.logo}</span>
                <span class={styles.ItemName}>{item.name}</span>
              </Marquee.Item>
            }
          </Marquee.Content>
        </Marquee.Viewport>
      </Marquee.Root>
    </div>
  </div>
}

```

### Pause on Interaction

Enable `pauseOnInteraction` to pause the marquee when users hover or focus on it, improving accessibility:

**Example: pause-on-interaction**

```ripple
import { Marquee } from 'ark-ripple/marquee';
import styles from 'styles/marquee.module.css';

const items = [
  { name: 'Apple', logo: '🍎' },
  { name: 'Banana', logo: '🍌' },
  { name: 'Cherry', logo: '🍒' },
  { name: 'Grape', logo: '🍇' },
  { name: 'Watermelon', logo: '🍉' },
  { name: 'Strawberry', logo: '🍓' },
];

export component PauseOnInteraction() {
  <Marquee.Root pauseOnInteraction class={styles.Root}>
    <Marquee.Viewport class={styles.Viewport}>
      <Marquee.Content class={styles.Content}>
        for (const item of items; key item.name) {
          <Marquee.Item class={styles.Item}>
            <span class={styles.ItemLogo}>{item.logo}</span>
            <span class={styles.ItemName}>{item.name}</span>
          </Marquee.Item>
        }
      </Marquee.Content>
    </Marquee.Viewport>
  </Marquee.Root>
}

```

### Programmatic Control

Use the `useMarquee` hook with `Marquee.RootProvider` to access the marquee API and control playback programmatically:

**Example: programmatic-control**

```ripple
import { Marquee, useMarquee } from 'ark-ripple/marquee';
import button from 'styles/button.module.css';
import styles from 'styles/marquee.module.css';

const items = [
  { name: 'Apple', logo: '🍎' },
  { name: 'Banana', logo: '🍌' },
  { name: 'Cherry', logo: '🍒' },
  { name: 'Grape', logo: '🍇' },
  { name: 'Watermelon', logo: '🍉' },
  { name: 'Strawberry', logo: '🍓' },
];

export component ProgrammaticControl() {
  const marquee = useMarquee({});

  <div class="stack">
    <Marquee.RootProvider value={marquee} class={styles.Root}>
      <Marquee.Viewport class={styles.Viewport}>
        <Marquee.Content class={styles.Content}>
          for (const item of items; key item.name) {
            <Marquee.Item class={styles.Item}>
              <span class={styles.ItemLogo}>{item.logo}</span>
              <span class={styles.ItemName}>{item.name}</span>
            </Marquee.Item>
          }
        </Marquee.Content>
      </Marquee.Viewport>
    </Marquee.RootProvider>

    <div class="hstack">
      <button
        type="button"
        class={button.Root}
        onClick={() => {
          @marquee.pause();
        }}
      >
        {'Pause'}
      </button>
      <button
        type="button"
        class={button.Root}
        onClick={() => {
          @marquee.resume();
        }}
      >
        {'Resume'}
      </button>
    </div>
  </div>
}

```

> If you're using the `Marquee.RootProvider` component, you don't need to use the `Marquee.Root` component.

### Loops

Set the `loopCount` prop to run the marquee a specific number of times. Use `onLoopComplete` to track each loop
iteration and `onComplete` to know when all loops finish:

**Example: finite-loops**

```ripple
import { Marquee } from 'ark-ripple/marquee';
import { track } from 'ripple';
import styles from 'styles/marquee.module.css';

const items = [
  { name: 'Apple', logo: '🍎' },
  { name: 'Banana', logo: '🍌' },
  { name: 'Cherry', logo: '🍒' },
  { name: 'Grape', logo: '🍇' },
  { name: 'Watermelon', logo: '🍉' },
  { name: 'Strawberry', logo: '🍓' },
];

export component FiniteLoops() {
  let loopCount = track(0);
  let completedCount = track(0);

  <div class="stack">
    <Marquee.Root
      loopCount={3}
      onLoopComplete={() => {
        @loopCount = @loopCount + 1;
      }}
      onComplete={() => {
        @completedCount = @completedCount + 1;
      }}
      class={styles.Root}
    >
      <Marquee.Viewport class={styles.Viewport}>
        <Marquee.Content class={styles.Content}>
          for (const item of items; key item.name) {
            <Marquee.Item class={styles.Item}>
              <span class={styles.ItemLogo}>{item.logo}</span>
              <span class={styles.ItemName}>{item.name}</span>
            </Marquee.Item>
          }
        </Marquee.Content>
      </Marquee.Viewport>
    </Marquee.Root>

    <div>
      <p>
        {'Loop completed: '}
        {@loopCount}
        {' times'}
      </p>
      <p>
        {'Animation completed: '}
        {@completedCount}
        {' times'}
      </p>
    </div>
  </div>
}

```

### Edges

Add `Marquee.Edge` components to create fade effects at the start and end of the scrolling area:

**Example: with-edges**

```ripple
import { Marquee } from 'ark-ripple/marquee';
import styles from 'styles/marquee.module.css';

const items = [
  { name: 'Apple', logo: '🍎' },
  { name: 'Banana', logo: '🍌' },
  { name: 'Cherry', logo: '🍒' },
  { name: 'Grape', logo: '🍇' },
  { name: 'Watermelon', logo: '🍉' },
  { name: 'Strawberry', logo: '🍓' },
];

export component WithEdges() {
  <Marquee.Root class={styles.Root}>
    <Marquee.Edge side="start" class={styles.Edge} />
    <Marquee.Viewport class={styles.Viewport}>
      <Marquee.Content class={styles.Content}>
        for (const item of items; key item.name) {
          <Marquee.Item class={styles.Item}>
            <span class={styles.ItemLogo}>{item.logo}</span>
            <span class={styles.ItemName}>{item.name}</span>
          </Marquee.Item>
        }
      </Marquee.Content>
    </Marquee.Viewport>
    <Marquee.Edge side="end" class={styles.Edge} />
  </Marquee.Root>
}

```

## Guides

### Content Animation

The Marquee component requires CSS keyframe animations to function properly. You'll need to define animations for both
horizontal and vertical scrolling:

```css
@keyframes marqueeX {
  from {
    transform: translateX(0);
  }
  to {
    transform: translateX(var(--marquee-translate));
  }
}

@keyframes marqueeY {
  from {
    transform: translateY(0);
  }
  to {
    transform: translateY(var(--marquee-translate));
  }
}
```

The component automatically applies the appropriate animation (`marqueeX` or `marqueeY`) based on the scroll direction
and uses the `--marquee-translate` CSS variable for seamless looping.

You can target specific parts of the marquee using `data-part` attributes for custom styling:

- `[data-part="root"]` - The root container
- `[data-part="viewport"]` - The scrolling viewport
- `[data-part="content"]` - The content wrapper (receives animation)
- `[data-part="item"]` - Individual marquee items
- `[data-part="edge"]` - Edge gradient overlays

### Best Practices

- **Enable pause-on-interaction**: Use `pauseOnInteraction` to allow users to pause animations on hover or focus,
  improving accessibility and readability
- **Use descriptive labels**: Provide meaningful `aria-label` values that describe the marquee content (e.g., "Partner
  logos", "Latest announcements")
- **Avoid for critical information**: Don't use marquees for essential content that users must read, as continuously
  moving text can be difficult to process. Consider static displays for important information

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `autoFill` | `boolean` | No | Whether to automatically duplicate content to fill the container. |
| `defaultPaused` | `boolean` | No | Whether the marquee is paused by default. |
| `delay` | `number` | No | The delay before the animation starts (in seconds). |
| `ids` | `Partial<{ root: string; viewport: string; content: (index: number) => string }>` | No | The ids of the elements in the marquee. Useful for composition. |
| `loopCount` | `number` | No | The number of times to loop the animation (0 = infinite). |
| `onComplete` | `() => void` | No | Function called when the marquee completes all loops and stops.
Only fires for finite loops (loopCount > 0). |
| `onLoopComplete` | `() => void` | No | Function called when the marquee completes one loop iteration. |
| `onPauseChange` | `(details: PauseStatusDetails) => void` | No | Function called when the pause status changes. |
| `paused` | `boolean` | No | Whether the marquee is paused. |
| `pauseOnInteraction` | `boolean` | No | Whether to pause the marquee on user interaction (hover, focus). |
| `reverse` | `boolean` | No | Whether to reverse the animation direction. |
| `side` | `Side` | No | The side/direction the marquee scrolls towards. |
| `spacing` | `string` | No | The spacing between marquee items. |
| `speed` | `number` | No | The speed of the marquee animation in pixels per second. |
| `translations` | `IntlTranslations` | No | The localized messages to use. |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | marquee |
| `[data-part]` | root |
| `[data-state]` | "paused" | "idle" |
| `[data-orientation]` | The orientation of the marquee |
| `[data-paused]` | Present when paused |


**Root CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--marquee-duration` | The marquee duration value for the Root |
| `--marquee-spacing` | The marquee spacing value for the Root |
| `--marquee-delay` | The marquee delay value for the Root |
| `--marquee-loop-count` | The marquee loop count value for the Root |
| `--marquee-translate` | The marquee translate value for the Root |


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | marquee |
| `[data-part]` |  |
| `[data-index]` | The index of the item |
| `[data-orientation]` | The orientation of the content |
| `[data-side]` |  |
| `[data-reverse]` |  |
| `[data-clone]` |  |


**Edge Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `side` | `Side` | Yes | The side where the edge gradient should appear. |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Edge Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | marquee |
| `[data-part]` |  |
| `[data-side]` |  |
| `[data-orientation]` | The orientation of the edge |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseMarqueeReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Viewport Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Viewport Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | marquee |
| `[data-part]` |  |
| `[data-orientation]` | The orientation of the viewport |
| `[data-side]` |  |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `paused` | `boolean` | Whether the marquee is currently paused. |
| `orientation` | `"horizontal" | "vertical"` | The current orientation of the marquee. |
| `side` | `Side` | The current side/direction of the marquee. |
| `multiplier` | `number` | The multiplier for auto-fill. Indicates how many times to duplicate content.
When autoFill is enabled and content is smaller than container, this returns
the number of additional copies needed. Otherwise returns 1. |
| `contentCount` | `number` | The total number of content elements to render (original + clones).
Use this value when rendering your content in a loop. |
| `pause` | `VoidFunction` | Pause the marquee animation. |
| `resume` | `VoidFunction` | Resume the marquee animation. |
| `togglePause` | `VoidFunction` | Toggle the pause state. |
| `restart` | `VoidFunction` | Restart the marquee animation from the beginning. |



# Menu 



## Anatomy



```tsx
<Menu.Root>
  <Menu.Trigger>
    <Menu.Indicator />
  </Menu.Trigger>
  <Menu.Positioner>
    <Menu.Content>
      <Menu.Arrow>
        <Menu.ArrowTip />
      </Menu.Arrow>
      <Menu.Item />
      <Menu.ItemGroup>
        <Menu.ItemGroupLabel />
        <Menu.Item />
      </Menu.ItemGroup>
      <Menu.Separator />
    </Menu.Content>
  </Menu.Positioner>
</Menu.Root>
```

## Examples

**Example: basic**

```ripple
import { Menu } from 'ark-ripple/menu';
import { ChevronDown } from 'lucide-ripple';
import styles from 'styles/menu.module.css';

export component Basic() {
  <Menu.Root>
    <Menu.Trigger class={styles.Trigger}>
      {'File'}
      <Menu.Indicator class={styles.Indicator}>
        <ChevronDown />
      </Menu.Indicator>
    </Menu.Trigger>
    <Menu.Positioner>
      <Menu.Content class={styles.Content}>
        <Menu.Item class={styles.Item} value="new-file">{'New File'}</Menu.Item>
        <Menu.Item class={styles.Item} value="open">{'Open...'}</Menu.Item>
        <Menu.Item class={styles.Item} value="save">{'Save'}</Menu.Item>
        <Menu.Item class={styles.Item} value="save-as">{'Save As...'}</Menu.Item>
      </Menu.Content>
    </Menu.Positioner>
  </Menu.Root>
}

```

### Item Selection

Use `onSelect` to handle item selection. The callback receives the item's `id`.

**Example: controlled**

```ripple
import { Menu } from 'ark-ripple/menu';
import { ChevronDown } from 'lucide-ripple';
import { track } from 'ripple';
import button from 'styles/button.module.css';
import styles from 'styles/menu.module.css';

export component Controlled() {
  let open = track(false);

  <div class="stack">
    <button
      type="button"
      class={button.Root}
      onclick={() => {
        @open = !@open;
      }}
    >
      {'Toggle'}
    </button>
    <Menu.Root
      {open}
      onOpenChange={(e) => {
        @open = e.open;
      }}
    >
      <Menu.Trigger class={styles.Trigger}>
        {'Actions'}
        <Menu.Indicator class={styles.Indicator}>
          <ChevronDown />
        </Menu.Indicator>
      </Menu.Trigger>
      <Menu.Positioner>
        <Menu.Content class={styles.Content}>
          <Menu.Item class={styles.Item} value="edit">{'Edit'}</Menu.Item>
          <Menu.Item class={styles.Item} value="duplicate">{'Duplicate'}</Menu.Item>
          <Menu.Item class={styles.Item} value="archive">{'Archive'}</Menu.Item>
          <Menu.Item class={styles.Item} value="delete">{'Delete'}</Menu.Item>
        </Menu.Content>
      </Menu.Positioner>
    </Menu.Root>
  </div>
}

```

### Root Provider

An alternative way to control the menu is to use the `RootProvider` component and the `useMenu` hook. This way you can
access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { Menu, useMenu } from 'ark-ripple/menu';
import { ChevronDown } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/menu.module.css';

export component RootProvider() {
  const menu = useMenu();

  <div class="stack">
    <button class={button.Root} onclick={() => menu.@api.setHighlightedValue('copy')}>
      {'Highlight Copy'}
    </button>
    <Menu.RootProvider value={menu}>
      <Menu.Trigger class={styles.Trigger}>
        {'Edit'}
        <Menu.Indicator class={styles.Indicator}>
          <ChevronDown />
        </Menu.Indicator>
      </Menu.Trigger>
      <Menu.Positioner>
        <Menu.Content class={styles.Content}>
          <Menu.Item class={styles.Item} value="cut">{'Cut'}</Menu.Item>
          <Menu.Item class={styles.Item} value="copy">{'Copy'}</Menu.Item>
          <Menu.Item class={styles.Item} value="paste">{'Paste'}</Menu.Item>
          <Menu.Item class={styles.Item} value="delete">{'Delete'}</Menu.Item>
        </Menu.Content>
      </Menu.Positioner>
    </Menu.RootProvider>
  </div>
}

```

### Grouping

Use `Menu.ItemGroup` and `Menu.ItemGroupLabel` to organize related menu items.

**Example: group**

```ripple
import { Menu } from 'ark-ripple/menu';
import { ChevronDown } from 'lucide-ripple';
import styles from 'styles/menu.module.css';

export component Group() {
  <Menu.Root>
    <Menu.Trigger class={styles.Trigger}>
      {'Edit'}
      <Menu.Indicator class={styles.Indicator}>
        <ChevronDown />
      </Menu.Indicator>
    </Menu.Trigger>
    <Menu.Positioner>
      <Menu.Content class={styles.Content}>
        <Menu.ItemGroup class={styles.ItemGroup}>
          <Menu.ItemGroupLabel class={styles.ItemGroupLabel}>{'Clipboard'}</Menu.ItemGroupLabel>
          <Menu.Item class={styles.Item} value="cut">{'Cut'}</Menu.Item>
          <Menu.Item class={styles.Item} value="copy">{'Copy'}</Menu.Item>
          <Menu.Item class={styles.Item} value="paste">{'Paste'}</Menu.Item>
        </Menu.ItemGroup>
        <Menu.ItemGroup class={styles.ItemGroup}>
          <Menu.ItemGroupLabel class={styles.ItemGroupLabel}>{'Selection'}</Menu.ItemGroupLabel>
          <Menu.Item class={styles.Item} value="select-all">{'Select All'}</Menu.Item>
          <Menu.Item class={styles.Item} value="deselect">{'Deselect'}</Menu.Item>
        </Menu.ItemGroup>
      </Menu.Content>
    </Menu.Positioner>
  </Menu.Root>
}

```

### Links

To render menu items as links, use the `asChild` prop to replace the default element with an anchor tag.

**Example: links**

```ripple
import { Menu } from 'ark-ripple/menu';
import { ChevronDown } from 'lucide-ripple';
import styles from 'styles/menu.module.css';

export component Links() {
  <Menu.Root>
    <Menu.Trigger class={styles.Trigger}>
      {'Help'}
      <Menu.Indicator class={styles.Indicator}>
        <ChevronDown />
      </Menu.Indicator>
    </Menu.Trigger>
    <Menu.Positioner>
      <Menu.Content class={styles.Content}>
        <Menu.Item class={styles.Item} value="docs">
          component asChild({ propsFn }) {
            <a {...propsFn({ href: 'https://ark-ui.rip' })}>{'Documentation'}</a>
          }
        </Menu.Item>
        <Menu.Item class={styles.Item} value="github">
          component asChild({ propsFn }) {
            <a {...propsFn({ href: 'https://github.com/chakra-ui/ark' })}>{'GitHub'}</a>
          }
        </Menu.Item>
        <Menu.Separator class={styles.Separator} />
        <Menu.Item class={styles.Item} value="changelog">
          component asChild({ propsFn }) {
            <a {...propsFn({ href: 'https://github.com/chakra-ui/ark/releases' })}>{'Changelog'}</a>
          }
        </Menu.Item>
      </Menu.Content>
    </Menu.Positioner>
  </Menu.Root>
}

```

### Checkbox

To add a checkbox to a menu item, use the `Menu.Checkbox` component.

**Example: checkbox-items**

```ripple
import { Menu } from 'ark-ripple/menu';
import { Check, ChevronDown } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/menu.module.css';

export component CheckboxItems() {
  let showToolbar = track(true);
  let showStatusBar = track(false);

  <Menu.Root>
    <Menu.Trigger class={styles.Trigger}>
      {'View'}
      <Menu.Indicator class={styles.Indicator}>
        <ChevronDown />
      </Menu.Indicator>
    </Menu.Trigger>
    <Menu.Positioner>
      <Menu.Content class={styles.Content}>
        <Menu.CheckboxItem
          class={styles.CheckboxItem}
          checked={showToolbar}
          onCheckedChange={(v) => {
            @showToolbar = v;
          }}
          value="toolbar"
        >
          <Menu.ItemIndicator class={styles.ItemIndicator}>
            <Check />
          </Menu.ItemIndicator>
          <Menu.ItemText class={styles.ItemText}>{'Show Toolbar'}</Menu.ItemText>
        </Menu.CheckboxItem>
        <Menu.CheckboxItem
          class={styles.CheckboxItem}
          checked={showStatusBar}
          onCheckedChange={(v) => {
            @showStatusBar = v;
          }}
          value="status-bar"
        >
          <Menu.ItemIndicator class={styles.ItemIndicator}>
            <Check />
          </Menu.ItemIndicator>
          <Menu.ItemText class={styles.ItemText}>{'Show Status Bar'}</Menu.ItemText>
        </Menu.CheckboxItem>
      </Menu.Content>
    </Menu.Positioner>
  </Menu.Root>
}

```

### Radio Group

To group radio option items, use the `Menu.RadioGroup` component.

**Example: radio-items**

```ripple
import { Menu } from 'ark-ripple/menu';
import { Check, ChevronDown } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/menu.module.css';

export component RadioItems() {
  let sortBy = track('date');

  <Menu.Root>
    <Menu.Trigger class={styles.Trigger}>
      {'Sort'}
      <Menu.Indicator class={styles.Indicator}>
        <ChevronDown />
      </Menu.Indicator>
    </Menu.Trigger>
    <Menu.Positioner>
      <Menu.Content class={styles.Content}>
        <Menu.RadioItemGroup
          class={styles.ItemGroup}
          value={sortBy}
          onValueChange={(e) => {
            @sortBy = e.value;
          }}
        >
          <Menu.ItemGroupLabel class={styles.ItemGroupLabel}>{'Sort By'}</Menu.ItemGroupLabel>
          <Menu.RadioItem class={styles.RadioItem} value="name">
            <Menu.ItemIndicator class={styles.ItemIndicator}>
              <Check />
            </Menu.ItemIndicator>
            <Menu.ItemText class={styles.ItemText}>{'Name'}</Menu.ItemText>
          </Menu.RadioItem>
          <Menu.RadioItem class={styles.RadioItem} value="date">
            <Menu.ItemIndicator class={styles.ItemIndicator}>
              <Check />
            </Menu.ItemIndicator>
            <Menu.ItemText class={styles.ItemText}>{'Date Modified'}</Menu.ItemText>
          </Menu.RadioItem>
          <Menu.RadioItem class={styles.RadioItem} value="size">
            <Menu.ItemIndicator class={styles.ItemIndicator}>
              <Check />
            </Menu.ItemIndicator>
            <Menu.ItemText class={styles.ItemText}>{'Size'}</Menu.ItemText>
          </Menu.RadioItem>
          <Menu.RadioItem class={styles.RadioItem} value="type">
            <Menu.ItemIndicator class={styles.ItemIndicator}>
              <Check />
            </Menu.ItemIndicator>
            <Menu.ItemText class={styles.ItemText}>{'Type'}</Menu.ItemText>
          </Menu.RadioItem>
        </Menu.RadioItemGroup>
      </Menu.Content>
    </Menu.Positioner>
  </Menu.Root>
}

```

### 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.

**Example: context**

```ripple
import { Menu } from 'ark-ripple/menu';
import styles from 'styles/menu.module.css';

export component Context() {
  <Menu.Root>
    <Menu.ContextTrigger class={styles.ContextTrigger}>{'Right click here'}</Menu.ContextTrigger>
    <Menu.Positioner>
      <Menu.Content class={styles.Content}>
        <Menu.Item class={styles.Item} value="cut">{'Cut'}</Menu.Item>
        <Menu.Item class={styles.Item} value="copy">{'Copy'}</Menu.Item>
        <Menu.Item class={styles.Item} value="paste">{'Paste'}</Menu.Item>
        <Menu.Separator class={styles.Separator} />
        <Menu.Item class={styles.Item} value="delete">{'Delete'}</Menu.Item>
      </Menu.Content>
    </Menu.Positioner>
  </Menu.Root>
}

```

### Nested

To show a nested menu, render another `Menu` component and use the `Menu.TriggerItem` component to open the submenu.

**Example: nested**

```ripple
import { Menu } from 'ark-ripple/menu';
import { ChevronDown } from 'lucide-ripple';
import styles from 'styles/menu.module.css';

export component Nested() {
  <Menu.Root>
    <Menu.Trigger class={styles.Trigger}>
      {'File'}
      <Menu.Indicator class={styles.Indicator}>
        <ChevronDown />
      </Menu.Indicator>
    </Menu.Trigger>
    <Menu.Positioner>
      <Menu.Content class={styles.Content}>
        <Menu.Item class={styles.Item} value="new">{'New File'}</Menu.Item>
        <Menu.Item class={styles.Item} value="open">{'Open...'}</Menu.Item>
        <Menu.Separator class={styles.Separator} />
        <Menu.Root>
          <Menu.TriggerItem class={styles.TriggerItem}>{'Share'}</Menu.TriggerItem>
          <Menu.Positioner>
            <Menu.Content class={styles.Content}>
              <Menu.Item class={styles.Item} value="email">{'Email'}</Menu.Item>
              <Menu.Item class={styles.Item} value="message">{'Message'}</Menu.Item>
              <Menu.Item class={styles.Item} value="airdrop">{'AirDrop'}</Menu.Item>
            </Menu.Content>
          </Menu.Positioner>
        </Menu.Root>
        <Menu.Root>
          <Menu.TriggerItem class={styles.TriggerItem}>{'Export'}</Menu.TriggerItem>
          <Menu.Positioner>
            <Menu.Content class={styles.Content}>
              <Menu.Item class={styles.Item} value="pdf">{'PDF'}</Menu.Item>
              <Menu.Item class={styles.Item} value="png">{'PNG'}</Menu.Item>
              <Menu.Item class={styles.Item} value="svg">{'SVG'}</Menu.Item>
            </Menu.Content>
          </Menu.Positioner>
        </Menu.Root>
        <Menu.Separator class={styles.Separator} />
        <Menu.Item class={styles.Item} value="print">{'Print...'}</Menu.Item>
      </Menu.Content>
    </Menu.Positioner>
  </Menu.Root>
}

```

### Menu in Dialog

When rendering a menu inside a dialog, use `lazyMount` and `unmountOnExit` to ensure proper cleanup when the dialog
closes.

**Example: menu-in-dialog**

```ripple
import { Dialog } from 'ark-ripple/dialog';
import { Menu } from 'ark-ripple/menu';
import { Portal } from 'ark-ripple/portal';
import { ChevronDown, X } from 'lucide-ripple';
import button from 'styles/button.module.css';
import dialog from 'styles/dialog.module.css';
import styles from 'styles/menu.module.css';

export component MenuInDialog() {
  <Dialog.Root>
    <Dialog.Trigger class={button.Root}>{'Open Dialog'}</Dialog.Trigger>
    <Portal>
      <Dialog.Backdrop class={dialog.Backdrop} />
      <Dialog.Positioner class={dialog.Positioner}>
        <Dialog.Content class={dialog.Content}>
          <Dialog.Title class={dialog.Title}>{'Settings'}</Dialog.Title>
          <Dialog.Description class={dialog.Description}>
            {'Configure your preferences below.'}
          </Dialog.Description>
          <Dialog.CloseTrigger class={dialog.CloseTrigger}>
            <X />
          </Dialog.CloseTrigger>
          <div class={dialog.Body}>
            <Menu.Root lazyMount unmountOnExit>
              <Menu.Trigger class={styles.Trigger}>
                {'Select theme'}
                <Menu.Indicator class={styles.Indicator}>
                  <ChevronDown />
                </Menu.Indicator>
              </Menu.Trigger>
              <Portal>
                <Menu.Positioner>
                  <Menu.Content class={styles.Content}>
                    <Menu.Arrow class={styles.Arrow}>
                      <Menu.ArrowTip class={styles.ArrowTip} />
                    </Menu.Arrow>
                    <Menu.Item class={styles.Item} value="light">{'Light'}</Menu.Item>
                    <Menu.Item class={styles.Item} value="dark">{'Dark'}</Menu.Item>
                    <Menu.Item class={styles.Item} value="system">{'System'}</Menu.Item>
                  </Menu.Content>
                </Menu.Positioner>
              </Portal>
            </Menu.Root>
          </div>
        </Dialog.Content>
      </Dialog.Positioner>
    </Portal>
  </Dialog.Root>
}

```

### Menu Item Dialog

Open a confirmation dialog from a menu item. This pattern is useful for destructive actions like delete that require
user confirmation.

**Example: menu-item-dialog**

```ripple
import { Dialog } from 'ark-ripple/dialog';
import { Menu } from 'ark-ripple/menu';
import { Portal } from 'ark-ripple/portal';
import { ChevronDown, X } from 'lucide-ripple';
import { track } from 'ripple';
import button from 'styles/button.module.css';
import dialog from 'styles/dialog.module.css';
import styles from 'styles/menu.module.css';

export component MenuItemDialog() {
  let dialogOpen = track(false);

  <Menu.Root>
    <Menu.Trigger class={styles.Trigger}>
      {'Actions'}
      <Menu.Indicator class={styles.Indicator}>
        <ChevronDown />
      </Menu.Indicator>
    </Menu.Trigger>
    <Portal>
      <Menu.Positioner>
        <Menu.Content class={styles.Content}>
          <Menu.Item class={styles.Item} value="edit">{'Edit'}</Menu.Item>
          <Menu.Item class={styles.Item} value="duplicate">{'Duplicate'}</Menu.Item>
          <Menu.Separator class={styles.Separator} />
          <Menu.Item
            class={styles.Item}
            value="delete"
            onSelect={() => {
              @dialogOpen = true;
            }}
          >
            {'Delete...'}
          </Menu.Item>
        </Menu.Content>
      </Menu.Positioner>
    </Portal>
  </Menu.Root>

  <Dialog.Root
    open={dialogOpen}
    onOpenChange={(e) => {
      @dialogOpen = e.open;
    }}
    role="alertdialog"
  >
    <Portal>
      <Dialog.Backdrop class={dialog.Backdrop} />
      <Dialog.Positioner class={dialog.Positioner}>
        <Dialog.Content class={dialog.Content}>
          <Dialog.Title class={dialog.Title}>{'Confirm Delete'}</Dialog.Title>
          <Dialog.Description class={dialog.Description}>
            {'Are you sure you want to delete this item? This action cannot be undone.'}
          </Dialog.Description>
          <Dialog.CloseTrigger class={dialog.CloseTrigger}>
            <X />
          </Dialog.CloseTrigger>
          <div class={dialog.Actions}>
            <button
              class={button.Root}
              onclick={() => {
                @dialogOpen = false;
              }}
            >
              {'Cancel'}
            </button>
            <button
              class={button.Root}
              data-variant="solid"
              onclick={() => {
                @dialogOpen = false;
              }}
            >
              {'Delete'}
            </button>
          </div>
        </Dialog.Content>
      </Dialog.Positioner>
    </Portal>
  </Dialog.Root>
}

```

## Guides

### Custom IDs

Ark UI autogenerates ids for menu items internally. Passing a custom `id` prop breaks the internal `getElementById`
functionality used by the component.

```tsx
// ❌ Don't do this
<Menu.Item id="custom-id" value="custom-value">
  Custom Item
</Menu.Item>

// ✅ Do this
<Menu.Item value="custom-value">
  Custom Item
</Menu.Item>
```

### Links

To render a menu item as a link, render the link as the menu item itself using `asChild`, not as a child of the
menu item.

> This pattern ensures the link element receives the correct ARIA attributes and keyboard interactions from the menu
> item.

Here's an example of a reusable `MenuItemLink` component:

```tsx
interface MenuItemLinkProps extends Menu.ItemProps {
  href?: string
  target?: string
}

export component MenuItemLink({ href, target, children, ...rest }: MenuItemLinkProps) {
  return (
    <Menu.Item>
      component asChild({ propsFn }) {
        <a {...propsFn({...rest, href, target })}>
          <@children />
        </a>
      }
    </Menu.Item>
  )
}
```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `anchorPoint` | `Point` | No | The positioning point for the menu. Can be set by the context menu trigger or the button trigger. |
| `aria-label` | `string` | No | The accessibility label for the menu |
| `closeOnSelect` | `boolean` | No | Whether to close the menu when an option is selected |
| `composite` | `boolean` | No | Whether the menu is a composed with other composite widgets like a combobox or tabs |
| `defaultHighlightedValue` | `string` | No | The initial highlighted value of the menu item when rendered.
Use when you don't need to control the highlighted value of the menu item. |
| `defaultOpen` | `boolean` | No | The initial open state of the menu when rendered.
Use when you don't need to control the open state of the menu. |
| `highlightedValue` | `string` | No | The controlled highlighted value of the menu item. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{
  trigger: string
  contextTrigger: string
  content: string
  groupLabel: (id: string) => string
  group: (id: string) => string
  positioner: string
  arrow: string
}>` | No | The ids of the elements in the menu. Useful for composition. |
| `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `loopFocus` | `boolean` | No | Whether to loop the keyboard navigation. |
| `navigate` | `(details: NavigateDetails) => void` | No | Function to navigate to the selected item if it's an anchor element |
| `onEscapeKeyDown` | `(event: KeyboardEvent) => void` | No | Function called when the escape key is pressed |
| `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state |
| `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component |
| `onHighlightChange` | `(details: HighlightChangeDetails) => void` | No | Function called when the highlighted menu item changes. |
| `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component |
| `onOpenChange` | `(details: OpenChangeDetails) => void` | No | Function called when the menu opens or closes |
| `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component |
| `onRequestDismiss` | `(event: LayerDismissEvent) => void` | No | Function called when this layer is closed due to a parent layer being closed |
| `onSelect` | `(details: SelectionDetails) => void` | No | Function called when a menu item is selected. |
| `open` | `boolean` | No | The controlled open state of the menu |
| `positioning` | `PositioningOptions` | No | The options used to dynamically position the menu |
| `present` | `boolean` | No | Whether the node is present (controlled by the user) |
| `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. |
| `typeahead` | `boolean` | No | Whether the pressing printable characters should trigger typeahead navigation |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


**Arrow Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Arrow CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--arrow-size` | The size of the arrow |
| `--arrow-size-half` | Half the size of the arrow |
| `--arrow-background` | Use this variable to style the arrow background |
| `--arrow-offset` | The offset position of the arrow |


**ArrowTip Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**CheckboxItem Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `checked` | `boolean` | Yes | Whether the option is checked |
| `value` | `string` | Yes | The value of the option |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `closeOnSelect` | `boolean` | No | Whether the menu should be closed when the option is selected. |
| `disabled` | `boolean` | No | Whether the menu item is disabled |
| `onCheckedChange` | `(checked: boolean) => void` | No | Function called when the option state is changed |
| `valueText` | `string` | No | The textual value of the option. Used in typeahead navigation of the menu.
If not provided, the text content of the menu item will be used. |


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | menu |
| `[data-part]` | content |
| `[data-state]` | "open" | "closed" |
| `[data-nested]` | menu |
| `[data-has-nested]` | menu |
| `[data-placement]` | The placement of the content |


**Content CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--layer-index` | The index of the dismissable in the layer stack |
| `--nested-layer-count` | The number of nested menus |


**ContextTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ContextTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | menu |
| `[data-part]` | context-trigger |
| `[data-state]` | "open" | "closed" |


**Indicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Indicator Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | menu |
| `[data-part]` | indicator |
| `[data-state]` | "open" | "closed" |


**ItemGroupLabel Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemGroup Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemIndicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemIndicator Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | menu |
| `[data-part]` | item-indicator |
| `[data-disabled]` | Present when disabled |
| `[data-highlighted]` | Present when highlighted |
| `[data-state]` | "checked" |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `string` | Yes | The unique value of the menu item option. |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `closeOnSelect` | `boolean` | No | Whether the menu should be closed when the option is selected. |
| `disabled` | `boolean` | No | Whether the menu item is disabled |
| `onSelect` | `VoidFunction` | No | The function to call when the item is selected |
| `valueText` | `string` | No | The textual value of the option. Used in typeahead navigation of the menu.
If not provided, the text content of the menu item will be used. |


**Item Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | menu |
| `[data-part]` | item |
| `[data-disabled]` | Present when disabled |
| `[data-highlighted]` | Present when highlighted |
| `[data-value]` | The value of the item |
| `[data-valuetext]` | The human-readable value |


**ItemText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemText Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | menu |
| `[data-part]` | item-text |
| `[data-disabled]` | Present when disabled |
| `[data-highlighted]` | Present when highlighted |
| `[data-state]` | "checked" |


**Positioner Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Positioner CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--reference-width` | The width of the reference element |
| `--reference-height` | The height of the root |
| `--available-width` | The available width in viewport |
| `--available-height` | The available height in viewport |
| `--x` | The x position for transform |
| `--y` | The y position for transform |
| `--z-index` | The z-index value |
| `--transform-origin` | The transform origin for animations |


**RadioItemGroup Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `onValueChange` | `(e: ValueChangeDetails) => void` | No |  |
| `value` | `string` | No |  |


**RadioItem Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `string` | Yes | The value of the option |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `closeOnSelect` | `boolean` | No | Whether the menu should be closed when the option is selected. |
| `disabled` | `boolean` | No | Whether the menu item is disabled |
| `valueText` | `string` | No | The textual value of the option. Used in typeahead navigation of the menu.
If not provided, the text content of the menu item will be used. |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseMenuReturn` | Yes |  |
| `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state |
| `present` | `boolean` | No | Whether the node is present (controlled by the user) |
| `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


**Separator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**TriggerItem Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | menu |
| `[data-part]` | trigger |
| `[data-placement]` | The placement of the trigger |
| `[data-controls]` |  |
| `[data-state]` | "open" | "closed" |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `open` | `boolean` | Whether the menu is open |
| `setOpen` | `(open: boolean) => void` | Function to open or close the menu |
| `highlightedValue` | `string` | The id of the currently highlighted menuitem |
| `setHighlightedValue` | `(value: string) => void` | Function to set the highlighted menuitem |
| `setParent` | `(parent: ParentMenuService) => void` | Function to register a parent menu. This is used for submenus |
| `setChild` | `(child: ChildMenuService) => void` | Function to register a child menu. This is used for submenus |
| `reposition` | `(options?: Partial<PositioningOptions>) => void` | Function to reposition the popover |
| `getOptionItemState` | `(props: OptionItemProps) => OptionItemState` | Returns the state of the option item |
| `getItemState` | `(props: ItemProps) => ItemState` | Returns the state of the menu item |
| `addItemListener` | `(props: ItemListenerProps) => VoidFunction` | Setup the custom event listener for item selection event |


## Accessibility

Complies with the [Menu WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/).

### Keyboard Support

**`Space`**
Description: Activates/Selects the highlighted item

**`Enter`**
Description: Activates/Selects the highlighted item

**`ArrowDown`**
Description: Highlights the next item in the menu

**`ArrowUp`**
Description: Highlights the previous item in the menu

**`ArrowRight + ArrowLeft`**
Description: <span>When focus is on trigger, opens or closes the submenu depending on reading direction.</span>

**`Esc`**
Description: Closes the menu and moves focus to the trigger


# Number Input 



## Anatomy



```tsx
<NumberInput.Root>
  <NumberInput.Label />
  <NumberInput.Scrubber />
  <NumberInput.Control>
    <NumberInput.Input />
    <NumberInput.IncrementTrigger />
    <NumberInput.DecrementTrigger />
  </NumberInput.Control>
</NumberInput.Root>
```

## Examples

**Example: basic**

```ripple
import { NumberInput } from 'ark-ripple/number-input';
import { ChevronUp, ChevronDown } from 'lucide-ripple';
import styles from 'styles/number-input.module.css';

export component Basic() {
  <NumberInput.Root class={styles.Root}>
    <NumberInput.Label class={styles.Label}>{'Label'}</NumberInput.Label>
    <NumberInput.Control class={styles.Control}>
      <NumberInput.Input class={styles.Input} />
      <div class={styles.TriggerGroup}>
        <NumberInput.IncrementTrigger class={styles.IncrementTrigger}>
          <ChevronUp />
        </NumberInput.IncrementTrigger>
        <NumberInput.DecrementTrigger class={styles.DecrementTrigger}>
          <ChevronDown />
        </NumberInput.DecrementTrigger>
      </div>
    </NumberInput.Control>
  </NumberInput.Root>
}

```

### Min and Max

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.

**Example: min-max**

```ripple
import { NumberInput } from 'ark-ripple/number-input';
import { ChevronUp, ChevronDown } from 'lucide-ripple';
import styles from 'styles/number-input.module.css';

export component MinMax() {
  <NumberInput.Root class={styles.Root} min={0} max={10}>
    <NumberInput.Label class={styles.Label}>{'Label'}</NumberInput.Label>
    <NumberInput.Control class={styles.Control}>
      <NumberInput.Input class={styles.Input} />
      <div class={styles.TriggerGroup}>
        <NumberInput.IncrementTrigger class={styles.IncrementTrigger}>
          <ChevronUp />
        </NumberInput.IncrementTrigger>
        <NumberInput.DecrementTrigger class={styles.DecrementTrigger}>
          <ChevronDown />
        </NumberInput.DecrementTrigger>
      </div>
    </NumberInput.Control>
  </NumberInput.Root>
}

```

> To allow values outside the min/max range, set `clampValueOnBlur` to `false`.

### Precision

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`.

**Example: fraction-digits**

```ripple
import { NumberInput } from 'ark-ripple/number-input';
import { ChevronUp, ChevronDown } from 'lucide-ripple';
import styles from 'styles/number-input.module.css';

export component FractionDigits() {
  <NumberInput.Root
    class={styles.Root}
    formatOptions={{ minimumFractionDigits: 2, maximumFractionDigits: 3 }}
    defaultValue="1.00"
  >
    <NumberInput.Label class={styles.Label}>{'Label'}</NumberInput.Label>
    <NumberInput.Control class={styles.Control}>
      <NumberInput.Input class={styles.Input} />
      <div class={styles.TriggerGroup}>
        <NumberInput.IncrementTrigger class={styles.IncrementTrigger}>
          <ChevronUp />
        </NumberInput.IncrementTrigger>
        <NumberInput.DecrementTrigger class={styles.DecrementTrigger}>
          <ChevronDown />
        </NumberInput.DecrementTrigger>
      </div>
    </NumberInput.Control>
  </NumberInput.Root>
}

```

### Scrubbing

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.

**Example: scrubber**

```ripple
import { NumberInput } from 'ark-ripple/number-input';
import { ChevronUp, ChevronDown, ArrowLeftRight } from 'lucide-ripple';
import styles from 'styles/number-input.module.css';

export component Scrubber() {
  <NumberInput.Root class={styles.Root} defaultValue="32">
    <NumberInput.Label class={styles.Label}>{'Label'}</NumberInput.Label>
    <NumberInput.Control class={styles.Control}>
      <NumberInput.Scrubber class={styles.Scrubber}>
        <ArrowLeftRight />
      </NumberInput.Scrubber>
      <NumberInput.Input class={styles.Input} data-has-scrubber />
      <div class={styles.TriggerGroup}>
        <NumberInput.IncrementTrigger class={styles.IncrementTrigger}>
          <ChevronUp />
        </NumberInput.IncrementTrigger>
        <NumberInput.DecrementTrigger class={styles.DecrementTrigger}>
          <ChevronDown />
        </NumberInput.DecrementTrigger>
      </div>
    </NumberInput.Control>
  </NumberInput.Root>
}

```

### Mouse Wheel

The NumberInput exposes a way to increment/decrement the value using the mouse wheel event. To activate this, set the
`allowMouseWheel` prop to `true`.

**Example: mouse-wheel**

```ripple
import { NumberInput } from 'ark-ripple/number-input';
import { ChevronUp, ChevronDown } from 'lucide-ripple';
import styles from 'styles/number-input.module.css';

export component MouseWheel() {
  <NumberInput.Root class={styles.Root} allowMouseWheel>
    <NumberInput.Label class={styles.Label}>{'Label'}</NumberInput.Label>
    <NumberInput.Control class={styles.Control}>
      <NumberInput.Input class={styles.Input} />
      <div class={styles.TriggerGroup}>
        <NumberInput.IncrementTrigger class={styles.IncrementTrigger}>
          <ChevronUp />
        </NumberInput.IncrementTrigger>
        <NumberInput.DecrementTrigger class={styles.DecrementTrigger}>
          <ChevronDown />
        </NumberInput.DecrementTrigger>
      </div>
    </NumberInput.Control>
  </NumberInput.Root>
}

```

### Formatting

To apply custom formatting to the input's value, set the `formatOptions` and provide `Intl.NumberFormatOptions` such as
`style` and `currency`.

**Example: formatting**

```ripple
import { NumberInput } from 'ark-ripple/number-input';
import { ChevronUp, ChevronDown } from 'lucide-ripple';
import styles from 'styles/number-input.module.css';

export component Formatting() {
  <NumberInput.Root
    class={styles.Root}
    formatOptions={{
      style: 'currency',
      currency: 'USD',
    }}
  >
    <NumberInput.Label class={styles.Label}>{'Label'}</NumberInput.Label>
    <NumberInput.Control class={styles.Control}>
      <NumberInput.Input class={styles.Input} />
      <div class={styles.TriggerGroup}>
        <NumberInput.IncrementTrigger class={styles.IncrementTrigger}>
          <ChevronUp />
        </NumberInput.IncrementTrigger>
        <NumberInput.DecrementTrigger class={styles.DecrementTrigger}>
          <ChevronDown />
        </NumberInput.DecrementTrigger>
      </div>
    </NumberInput.Control>
  </NumberInput.Root>
}

```

### Field

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.

**Example: with-field**

```ripple
import { Field } from 'ark-ripple/field';
import { NumberInput } from 'ark-ripple/number-input';
import { ChevronUp, ChevronDown } from 'lucide-ripple';
import field from 'styles/field.module.css';
import styles from 'styles/number-input.module.css';

export component WithField() {
  <Field.Root class={field.Root}>
    <NumberInput.Root class={styles.Root}>
      <NumberInput.Label class={styles.Label}>{'Label'}</NumberInput.Label>
      <NumberInput.Control class={styles.Control}>
        <NumberInput.Input class={styles.Input} />
        <div class={styles.TriggerGroup}>
          <NumberInput.IncrementTrigger class={styles.IncrementTrigger}>
            <ChevronUp />
          </NumberInput.IncrementTrigger>
          <NumberInput.DecrementTrigger class={styles.DecrementTrigger}>
            <ChevronDown />
          </NumberInput.DecrementTrigger>
        </div>
      </NumberInput.Control>
    </NumberInput.Root>
    <Field.HelperText class={field.HelperText}>{'Additional Info'}</Field.HelperText>
    <Field.ErrorText class={field.ErrorText}>{'Error Info'}</Field.ErrorText>
  </Field.Root>
}

```

### Root Provider

An alternative way to control the number input is to use the `RootProvider` component and the `useNumberInput` hook.
This way you can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { NumberInput, useNumberInput } from 'ark-ripple/number-input';
import { ChevronUp, ChevronDown } from 'lucide-ripple';
import styles from 'styles/number-input.module.css';

export component RootProvider() {
  const numberInput = useNumberInput();

  <div class="stack">
    <output>
      {'valueAsNumber: '}
      {@numberInput.valueAsNumber}
    </output>
    <NumberInput.RootProvider class={styles.Root} value={numberInput}>
      <NumberInput.Label class={styles.Label}>{'Label'}</NumberInput.Label>
      <NumberInput.Control class={styles.Control}>
        <NumberInput.Input class={styles.Input} />
        <div class={styles.TriggerGroup}>
          <NumberInput.IncrementTrigger class={styles.IncrementTrigger}>
            <ChevronUp />
          </NumberInput.IncrementTrigger>
          <NumberInput.DecrementTrigger class={styles.DecrementTrigger}>
            <ChevronDown />
          </NumberInput.DecrementTrigger>
        </div>
      </NumberInput.Control>
    </NumberInput.RootProvider>
  </div>
}

```

## Guides

### Scrubber

The `NumberInput.Scrubber` component provides an interactive scrub area that allows users to drag to change the input
value. It renders as a `<div>` element and displays a custom cursor element during scrubbing interactions.

This component utilizes the [Pointer Lock API](https://developer.mozilla.org/en-US/docs/Web/API/Pointer_Lock_API) for
smooth dragging interactions.

> **Note:** Browsers may show a notification when the Pointer Lock API is activated. The scrubber is automatically
> disabled in Safari to prevent layout shifts.

### Controlled

When controlling the NumberInput component, it's recommended to use string values instead of converting to numbers. This
is especially important when using `formatOptions` for currency or locale-specific formatting.

```tsx
const [value, setValue] = useState('0')

<NumberInput.Root value={value} onValueChange={(details) => setValue(details.value)}>
  {/* ... */}
</NumberInput.Root>
```

Converting values to numbers can cause issues with locale-specific formatting, particularly for currencies that use
different decimal and thousands separators (e.g., `1.523,30` vs `1,523.30`). By keeping values as strings, you preserve
the correct formatting and avoid parsing issues.

If you need to submit a numeric value in your form, use a hidden input that reads `valueAsNumber` from
`NumberInput.Context`:

```tsx
<NumberInput.Root value={value} onValueChange={(details) => setValue(details.value)}>
  <NumberInput.Input />
  <NumberInput.Context>
    {(context) => <input type="hidden" name="amount" value={context.valueAsNumber} />}
  </NumberInput.Context>
</NumberInput.Root>
```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `allowMouseWheel` | `boolean` | No | Whether to allow mouse wheel to change the value |
| `allowOverflow` | `boolean` | No | Whether to allow the value overflow the min/max range |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `clampValueOnBlur` | `boolean` | No | Whether to clamp the value when the input loses focus (blur) |
| `defaultValue` | `string` | No | The initial value of the input when rendered.
Use when you don't need to control the value of the input. |
| `disabled` | `boolean` | No | Whether the number input is disabled. |
| `focusInputOnChange` | `boolean` | No | Whether to focus input when the value changes |
| `form` | `string` | No | The associate form of the input element. |
| `formatOptions` | `NumberFormatOptions` | No | The options to pass to the `Intl.NumberFormat` constructor |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{
  root: string
  label: string
  input: string
  incrementTrigger: string
  decrementTrigger: string
  scrubber: string
}>` | No | The ids of the elements in the number input. Useful for composition. |
| `inputMode` | `InputMode` | No | Hints at the type of data that might be entered by the user. It also determines
the type of keyboard shown to the user on mobile devices |
| `invalid` | `boolean` | No | Whether the number input value is invalid. |
| `locale` | `string` | No | The current locale. Based on the BCP 47 definition. |
| `max` | `number` | No | The maximum value of the number input |
| `min` | `number` | No | The minimum value of the number input |
| `name` | `string` | No | The name attribute of the number input. Useful for form submission. |
| `onFocusChange` | `(details: FocusChangeDetails) => void` | No | Function invoked when the number input is focused |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | Function invoked when the value changes |
| `onValueCommit` | `(details: ValueChangeDetails) => void` | No | Function invoked when the value is committed (when the input is blurred or the Enter key is pressed) |
| `onValueInvalid` | `(details: ValueInvalidDetails) => void` | No | Function invoked when the value overflows or underflows the min/max range |
| `pattern` | `string` | No | The pattern used to check the <input> element's value against |
| `readOnly` | `boolean` | No | Whether the number input is readonly |
| `required` | `boolean` | No | Whether the number input is required |
| `spinOnPress` | `boolean` | No | Whether to spin the value when the increment/decrement button is pressed |
| `step` | `number` | No | The amount to increment or decrement the value by |
| `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states |
| `value` | `string` | No | The controlled value of the input |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | number-input |
| `[data-part]` | root |
| `[data-disabled]` | Present when disabled |
| `[data-focus]` | Present when focused |
| `[data-invalid]` | Present when invalid |
| `[data-scrubbing]` |  |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | number-input |
| `[data-part]` | control |
| `[data-focus]` | Present when focused |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]` | Present when invalid |
| `[data-scrubbing]` |  |


**DecrementTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**DecrementTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | number-input |
| `[data-part]` | decrement-trigger |
| `[data-disabled]` | Present when disabled |
| `[data-scrubbing]` |  |


**IncrementTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**IncrementTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | number-input |
| `[data-part]` | increment-trigger |
| `[data-disabled]` | Present when disabled |
| `[data-scrubbing]` |  |


**Input Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Input Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | number-input |
| `[data-part]` | input |
| `[data-invalid]` | Present when invalid |
| `[data-disabled]` | Present when disabled |
| `[data-scrubbing]` |  |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | number-input |
| `[data-part]` | label |
| `[data-disabled]` | Present when disabled |
| `[data-focus]` | Present when focused |
| `[data-invalid]` | Present when invalid |
| `[data-required]` | Present when required |
| `[data-scrubbing]` |  |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseNumberInputReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Scrubber Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Scrubber Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | number-input |
| `[data-part]` | scrubber |
| `[data-disabled]` | Present when disabled |
| `[data-scrubbing]` |  |


**ValueText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ValueText Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | number-input |
| `[data-part]` | value-text |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]` | Present when invalid |
| `[data-focus]` | Present when focused |
| `[data-scrubbing]` |  |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `focused` | `boolean` | Whether the input is focused. |
| `invalid` | `boolean` | Whether the input is invalid. |
| `empty` | `boolean` | Whether the input value is empty. |
| `value` | `string` | The formatted value of the input. |
| `valueAsNumber` | `number` | The value of the input as a number. |
| `setValue` | `(value: number) => void` | Function to set the value of the input. |
| `clearValue` | `VoidFunction` | Function to clear the value of the input. |
| `increment` | `VoidFunction` | Function to increment the value of the input by the step. |
| `decrement` | `VoidFunction` | Function to decrement the value of the input by the step. |
| `setToMax` | `VoidFunction` | Function to set the value of the input to the max. |
| `setToMin` | `VoidFunction` | Function to set the value of the input to the min. |
| `focus` | `VoidFunction` | Function to focus the input. |


## Accessibility

Complies with the [Spinbutton WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/).

### Keyboard Support

**`ArrowUp`**
Description: Increments the value of the number input by a predefined step.

**`ArrowDown`**
Description: Decrements the value of the number input by a predefined step.

**`PageUp`**
Description: Increments the value of the number input by a larger predefined step.

**`PageDown`**
Description: Decrements the value of the number input by a larger predefined step.

**`Home`**
Description: Sets the value of the number input to its minimum allowed value.

**`End`**
Description: Sets the value of the number input to its maximum allowed value.

**`Enter`**
Description: Submits the value entered in the number input.


# Pagination 



## Anatomy



```tsx
<Pagination.Root>
  <Pagination.PrevTrigger />
  <Pagination.Item />
  <Pagination.Ellipsis />
  <Pagination.NextTrigger />
</Pagination.Root>
```

## Examples

**Example: basic**

```ripple
import { Pagination } from 'ark-ripple/pagination';
import { ChevronLeft, ChevronRight } from 'lucide-ripple';
import styles from 'styles/pagination.module.css';

export component Basic() {
  <Pagination.Root count={5000} pageSize={10} siblingCount={2} class={styles.Root}>
    <div class={styles.Controls}>
      <Pagination.PrevTrigger class={styles.Trigger}>
        <ChevronLeft />
      </Pagination.PrevTrigger>
      <Pagination.Context>
        component children({ context }) {
          for (const [index, page] of @context.pages.entries(); key page.value) {
            if (page.type === 'page') {
              <Pagination.Item {...page} class={styles.Item}>{page.value}</Pagination.Item>
            } else {
              <Pagination.Ellipsis {index} class={styles.Ellipsis}>{'…'}</Pagination.Ellipsis>
            }
          }
        }
      </Pagination.Context>
      <Pagination.NextTrigger class={styles.Trigger}>
        <ChevronRight />
      </Pagination.NextTrigger>
    </div>
  </Pagination.Root>
}

```

### Controlled

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:

**Example: controlled**

```ripple
import { track } from 'ripple';
import { Pagination } from 'ark-ripple/pagination';
import { ChevronLeft, ChevronRight } from 'lucide-ripple';
import styles from 'styles/pagination.module.css';

export component Controlled() {
  let currentPage = track(1);

  <Pagination.Root
    count={5000}
    pageSize={10}
    siblingCount={2}
    page={currentPage}
    onPageChange={(details) => {
      @currentPage = details.page;
    }}
    class={styles.Root}
  >
    <div class={styles.Controls}>
      <Pagination.PrevTrigger class={styles.Trigger}>
        <ChevronLeft />
      </Pagination.PrevTrigger>
      <Pagination.Context>
        component children({ context }) {
          for (const [index, page] of @context.pages.entries(); key page.value) {
            if (page.type === 'page') {
              <Pagination.Item {...page} class={styles.Item}>{page.value}</Pagination.Item>
            } else {
              <Pagination.Ellipsis {index} class={styles.Ellipsis}>{'…'}</Pagination.Ellipsis>
            }
          }
        }
      </Pagination.Context>
      <Pagination.NextTrigger class={styles.Trigger}>
        <ChevronRight />
      </Pagination.NextTrigger>
    </div>
  </Pagination.Root>
}

```

### Root Provider

An alternative way to control the pagination is to use the `RootProvider` component and the `usePagination` hook. This
way you can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { Pagination, usePagination } from 'ark-ripple/pagination';
import { ChevronLeft, ChevronRight } from 'lucide-ripple';
import styles from 'styles/pagination.module.css';

export component RootProvider() {
  const pagination = usePagination({ count: 5000, pageSize: 10, siblingCount: 2 });

  <div class="stack">
    <button class={styles.Trigger} onClick={() => @pagination.goToNextPage()}>{'Next Page'}</button>

    <Pagination.RootProvider value={pagination} class={styles.Root}>
      <div class={styles.Controls}>
        <Pagination.PrevTrigger class={styles.Trigger}>
          <ChevronLeft />
        </Pagination.PrevTrigger>
        <Pagination.Context>
          component children({ context }) {
            for (const [index, page] of @context.pages.entries(); key page.value) {
              if (page.type === 'page') {
                <Pagination.Item {...page} class={styles.Item}>{page.value}</Pagination.Item>
              } else {
                <Pagination.Ellipsis {index} class={styles.Ellipsis}>{'…'}</Pagination.Ellipsis>
              }
            }
          }
        </Pagination.Context>
        <Pagination.NextTrigger class={styles.Trigger}>
          <ChevronRight />
        </Pagination.NextTrigger>
      </div>
    </Pagination.RootProvider>
  </div>
}

```

### Customization

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:

**Example: customized**

```ripple
import { Pagination } from 'ark-ripple/pagination';
import { ChevronLeft, ChevronRight } from 'lucide-ripple';
import styles from 'styles/pagination.module.css';

export component Customized() {
  <Pagination.Root
    count={5000}
    pageSize={20}
    siblingCount={3}
    translations={{
      nextTriggerLabel: 'Next',
      prevTriggerLabel: 'Prev',
      itemLabel: (details) => `Page ${details.page}`,
    }}
    class={styles.Root}
  >
    <div class={styles.Controls}>
      <Pagination.PrevTrigger class={styles.Trigger}>
        <ChevronLeft />
      </Pagination.PrevTrigger>
      <Pagination.Context>
        component children({ context }) {
          for (const [index, page] of @context.pages.entries(); key page.value) {
            if (page.type === 'page') {
              <Pagination.Item {...page} class={styles.Item}>{page.value}</Pagination.Item>
            } else {
              <Pagination.Ellipsis {index} class={styles.Ellipsis}>{'…'}</Pagination.Ellipsis>
            }
          }
        }
      </Pagination.Context>
      <Pagination.NextTrigger class={styles.Trigger}>
        <ChevronRight />
      </Pagination.NextTrigger>
    </div>
  </Pagination.Root>
}

```

### Context

Access pagination state and methods with `Pagination.Context` or the `usePaginationContext` hook. You get methods like
`setPage`, `setPageSize`, `goToNextPage`, `goToPrevPage`, `goToFirstPage`, `goToLastPage`, as well as properties like
`totalPages` and `pageRange`.

**Example: context**

```ripple
import { Pagination } from 'ark-ripple/pagination';
import { ChevronLeft, ChevronRight, ChevronsLeft, ChevronsRight } from 'lucide-ripple';
import styles from 'styles/pagination.module.css';

export component Context() {
  <Pagination.Root count={100} pageSize={10} class={styles.Root}>
    <Pagination.Context>
      component children({ context }) {
        <div class={styles.Controls}>
          <button class={styles.Trigger} onClick={() => @context.goToFirstPage()}>
            <ChevronsLeft />
          </button>
          <button class={styles.Trigger} onClick={() => @context.goToPrevPage()}>
            <ChevronLeft />
          </button>
          <p class={styles.Text} style="min-width: 120px; text-align: center">
            {'Page '}
            {@context.page}
            {' of '}
            {@context.totalPages}
          </p>
          <button class={styles.Trigger} onClick={() => @context.goToNextPage()}>
            <ChevronRight />
          </button>
          <button class={styles.Trigger} onClick={() => @context.goToLastPage()}>
            <ChevronsRight />
          </button>
        </div>
      }
    </Pagination.Context>
  </Pagination.Root>
}

```

### Data Slicing

Use the `slice()` method to paginate actual data arrays. This method automatically slices your data based on the current
page and page size.

**Example: data-slicing**

```ripple
import { Pagination } from 'ark-ripple/pagination';
import { ChevronLeft, ChevronRight } from 'lucide-ripple';
import styles from 'styles/pagination.module.css';

const users = [
  { id: 1, name: 'Emma Wilson', email: 'emma@example.com' },
  { id: 2, name: 'Liam Johnson', email: 'liam@example.com' },
  { id: 3, name: 'Olivia Brown', email: 'olivia@example.com' },
  { id: 4, name: 'Noah Davis', email: 'noah@example.com' },
  { id: 5, name: 'Ava Martinez', email: 'ava@example.com' },
  { id: 6, name: 'Ethan Garcia', email: 'ethan@example.com' },
  { id: 7, name: 'Sophia Rodriguez', email: 'sophia@example.com' },
  { id: 8, name: 'Mason Lee', email: 'mason@example.com' },
  { id: 9, name: 'Isabella Walker', email: 'isabella@example.com' },
  { id: 10, name: 'James Hall', email: 'james@example.com' },
  { id: 11, name: 'Mia Allen', email: 'mia@example.com' },
  { id: 12, name: 'Benjamin Young', email: 'benjamin@example.com' },
  { id: 13, name: 'Charlotte King', email: 'charlotte@example.com' },
  { id: 14, name: 'William Wright', email: 'william@example.com' },
  { id: 15, name: 'Amelia Scott', email: 'amelia@example.com' },
  { id: 16, name: 'Henry Green', email: 'henry@example.com' },
  { id: 17, name: 'Harper Adams', email: 'harper@example.com' },
  { id: 18, name: 'Sebastian Baker', email: 'sebastian@example.com' },
  { id: 19, name: 'Evelyn Nelson', email: 'evelyn@example.com' },
  { id: 20, name: 'Jack Carter', email: 'jack@example.com' },
];

export component DataSlicing() {
  <Pagination.Root count={users.length} pageSize={5} class={styles.Root}>
    <Pagination.Context>
      component children({ context }) {
        <div class={styles.Grid}>
          for (const user of @context.slice(users); key user.id) {
            <div class={styles.GridItem}>
              <span class={styles.GridItemTitle}>{user.name}</span>
              <span class={styles.GridItemText}>{user.email}</span>
            </div>
          }
        </div>

        <div class={styles.Controls}>
          <Pagination.PrevTrigger class={styles.Trigger}>
            <ChevronLeft />
          </Pagination.PrevTrigger>

          for (const [index, page] of @context.pages.entries(); key page.value) {
            if (page.type === 'page') {
              <Pagination.Item {...page} class={styles.Item}>{page.value}</Pagination.Item>
            } else {
              <Pagination.Ellipsis {index} class={styles.Ellipsis}>{'…'}</Pagination.Ellipsis>
            }
          }

          <Pagination.NextTrigger class={styles.Trigger}>
            <ChevronRight />
          </Pagination.NextTrigger>
        </div>
      }
    </Pagination.Context>
  </Pagination.Root>
}

```

### Page Range

Display the current page range information using the `pageRange` property. This shows which items are currently visible
(e.g., "Showing 1-10 of 100 results").

**Example: page-range**

```ripple
import { Pagination } from 'ark-ripple/pagination';
import { ChevronLeft, ChevronRight } from 'lucide-ripple';
import styles from 'styles/pagination.module.css';

export component PageRange() {
  <Pagination.Root count={100} pageSize={10} class={styles.Root}>
    <Pagination.Context>
      component children({ context }) {
        <div class={styles.Controls}>
          <Pagination.PrevTrigger class={styles.Trigger}>
            <ChevronLeft />
          </Pagination.PrevTrigger>

          for (const [index, page] of @context.pages.entries(); key page.value) {
            if (page.type === 'page') {
              <Pagination.Item {...page} class={styles.Item}>{page.value}</Pagination.Item>
            } else {
              <Pagination.Ellipsis {index} class={styles.Ellipsis}>{'…'}</Pagination.Ellipsis>
            }
          }

          <Pagination.NextTrigger class={styles.Trigger}>
            <ChevronRight />
          </Pagination.NextTrigger>
        </div>

        <div class="stack">
          <p class={styles.Text}>
            {'Showing '}
            {@context.pageRange.start + 1}
            {'-'}
            {@context.pageRange.end}
            {' of '}
            {@context.count}
            {' results'}
          </p>
          <p class={styles.Text}>
            {'Page '}
            {@context.page}
            {' of '}
            {@context.totalPages}
          </p>
        </div>
      }
    </Pagination.Context>
  </Pagination.Root>
}

```

### Page Size

Control the number of items per page dynamically using `setPageSize()`. This example shows how to integrate a native
select element to change the page size.

> **Note:** For uncontrolled behavior, use `defaultPageSize` to set the initial value. For controlled behavior, use
> `pageSize` and `onPageSizeChange` to programmatically manage the page size.

**Example: page-size-control**

```ripple
import { Pagination } from 'ark-ripple/pagination';
import { ChevronLeft, ChevronRight } from 'lucide-ripple';
import styles from 'styles/pagination.module.css';

export component PageSizeControl() {
  <Pagination.Root count={100} defaultPageSize={10} class={styles.Root}>
    <Pagination.Context>
      component children({ context }) {
        <div class="hstack">
          <label class={styles.Text}>{'Items per page:'}</label>
          <select
            class={styles.PageSizeSelect}
            value={@context.pageSize}
            onChange={(e) => @context.setPageSize(Number(e.target.value))}
          >
            <option value={5}>{'5'}</option>
            <option value={10}>{'10'}</option>
            <option value={20}>{'20'}</option>
            <option value={50}>{'50'}</option>
          </select>
        </div>

        <div class={styles.Controls}>
          <Pagination.PrevTrigger class={styles.Trigger}>
            <ChevronLeft />
          </Pagination.PrevTrigger>

          for (const [index, page] of @context.pages.entries(); key page.value) {
            if (page.type === 'page') {
              <Pagination.Item {...page} class={styles.Item}>{page.value}</Pagination.Item>
            } else {
              <Pagination.Ellipsis {index} class={styles.Ellipsis}>{'…'}</Pagination.Ellipsis>
            }
          }

          <Pagination.NextTrigger class={styles.Trigger}>
            <ChevronRight />
          </Pagination.NextTrigger>
        </div>

        <p class={styles.Text}>
          {'Page '}
          {@context.page}
          {' of '}
          {@context.totalPages}
        </p>
      }
    </Pagination.Context>
  </Pagination.Root>
}

```

### Links

Create pagination with link navigation for better SEO and accessibility. This example shows how to use the pagination
component with anchor links instead of buttons.

**Example: link**

```ripple
import { Pagination, usePagination } from 'ark-ripple/pagination';
import { ChevronLeft, ChevronRight } from 'lucide-ripple';
import styles from 'styles/pagination.module.css';

export component Link() {
  const pagination = usePagination(
    {
      type: 'link',
      count: 100,
      pageSize: 10,
      siblingCount: 2,
      getPageUrl: ({ page }) => `/page=${page}`,
    },
  );

  <Pagination.RootProvider value={pagination} class={styles.Root}>
    <div class={styles.Controls}>
      <a class={styles.Trigger} {...@pagination.getPrevTriggerProps()}>
        <ChevronLeft />
      </a>
      for (const [index, page] of @pagination.pages.entries(); key page.value) {
        if (page.type === 'page') {
          <a class={styles.Item} {...@pagination.getItemProps(page)}>{page.value}</a>
        } else {
          <span class={styles.Ellipsis} {...@pagination.getEllipsisProps({ index })}>{'…'}</span>
        }
      }
      <a class={styles.Trigger} {...@pagination.getNextTriggerProps()}>
        <ChevronRight />
      </a>
    </div>
  </Pagination.RootProvider>
}

```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `boundaryCount` | `number` | No | Number of pages to show at the beginning and end |
| `count` | `number` | No | Total number of data items |
| `defaultPage` | `number` | No | The initial active page when rendered.
Use when you don't need to control the active page of the pagination. |
| `defaultPageSize` | `number` | No | The initial number of data items per page when rendered.
Use when you don't need to control the page size of the pagination. |
| `getPageUrl` | `(details: PageUrlDetails) => string` | No | Function to generate href attributes for pagination links.
Only used when `type` is set to "link". |
| `ids` | `Partial<{
  root: string
  ellipsis: (index: number) => string
  firstTrigger: string
  prevTrigger: string
  nextTrigger: string
  lastTrigger: string
  item: (page: number) => string
}>` | No | The ids of the elements in the accordion. Useful for composition. |
| `onPageChange` | `(details: PageChangeDetails) => void` | No | Called when the page number is changed |
| `onPageSizeChange` | `(details: PageSizeChangeDetails) => void` | No | Called when the page size is changed |
| `page` | `number` | No | The controlled active page |
| `pageSize` | `number` | No | The controlled number of data items per page |
| `siblingCount` | `number` | No | Number of pages to show beside active page |
| `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states |
| `type` | `'button' | 'link'` | No | The type of the trigger element |


**Ellipsis Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**FirstTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**FirstTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | pagination |
| `[data-part]` | first-trigger |
| `[data-disabled]` | Present when disabled |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `type` | `'page'` | Yes |  |
| `value` | `number` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Item Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | pagination |
| `[data-part]` | item |
| `[data-index]` | The index of the item |
| `[data-selected]` | Present when selected |


**LastTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**LastTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | pagination |
| `[data-part]` | last-trigger |
| `[data-disabled]` | Present when disabled |


**NextTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**NextTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | pagination |
| `[data-part]` | next-trigger |
| `[data-disabled]` | Present when disabled |


**PrevTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**PrevTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | pagination |
| `[data-part]` | prev-trigger |
| `[data-disabled]` | Present when disabled |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UsePaginationReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `page` | `number` | The current page. |
| `count` | `number` | The total number of data items. |
| `pageSize` | `number` | The number of data items per page. |
| `totalPages` | `number` | The total number of pages. |
| `pages` | `Pages` | The page range. Represented as an array of page numbers (including ellipsis) |
| `previousPage` | `number` | The previous page. |
| `nextPage` | `number` | The next page. |
| `pageRange` | `PageRange` | The page range. Represented as an object with `start` and `end` properties. |
| `slice` | `<V>(data: V[]) => V[]` | Function to slice an array of data based on the current page. |
| `setPageSize` | `(size: number) => void` | Function to set the page size. |
| `setPage` | `(page: number) => void` | Function to set the current page. |
| `goToNextPage` | `VoidFunction` | Function to go to the next page. |
| `goToPrevPage` | `VoidFunction` | Function to go to the previous page. |
| `goToFirstPage` | `VoidFunction` | Function to go to the first page. |
| `goToLastPage` | `VoidFunction` | Function to go to the last page. |



# Password Input 



## Anatomy



```tsx
<PasswordInput.Root>
  <PasswordInput.Label />
  <PasswordInput.Control>
    <PasswordInput.Input />
    <PasswordInput.VisibilityTrigger>
      <PasswordInput.Indicator />
    </PasswordInput.VisibilityTrigger>
  </PasswordInput.Control>
</PasswordInput.Root>
```

## Examples

**Example: basic**

```ripple
import { PasswordInput } from 'ark-ripple/password-input';
import { Eye, EyeOff } from 'lucide-ripple';
import styles from 'styles/password-input.module.css';

export component Basic() {
  <PasswordInput.Root class={styles.Root}>
    <PasswordInput.Label class={styles.Label}>{'Password'}</PasswordInput.Label>
    <PasswordInput.Control class={styles.Control}>
      <PasswordInput.Input class={styles.Input} />
      <PasswordInput.VisibilityTrigger class={styles.VisibilityTrigger}>
        <PasswordInput.Indicator class={styles.Indicator} fallback={EyeOff}>
          <Eye />
        </PasswordInput.Indicator>
      </PasswordInput.VisibilityTrigger>
    </PasswordInput.Control>
  </PasswordInput.Root>
}

```

### Autocomplete

Use the `autoComplete` prop to manage autocompletion in the input.

- `new-password` — The user is creating a new password.
- `current-password` — The user is entering an existing password.

**Example: autocomplete**

```ripple
import { PasswordInput } from 'ark-ripple/password-input';
import { Eye, EyeOff } from 'lucide-ripple';
import styles from 'styles/password-input.module.css';

export component Autocomplete() {
  <PasswordInput.Root class={styles.Root} autoComplete="new-password">
    <PasswordInput.Label class={styles.Label}>{'Password'}</PasswordInput.Label>
    <PasswordInput.Control class={styles.Control}>
      <PasswordInput.Input class={styles.Input} />
      <PasswordInput.VisibilityTrigger class={styles.VisibilityTrigger}>
        <PasswordInput.Indicator class={styles.Indicator} fallback={EyeOff}>
          <Eye />
        </PasswordInput.Indicator>
      </PasswordInput.VisibilityTrigger>
    </PasswordInput.Control>
  </PasswordInput.Root>
}

```

### Controlled Visibility

Use the `visible` and `onVisibilityChange` props to control the visibility of the password input.

**Example: controlled-visibility**

```ripple
import { PasswordInput } from 'ark-ripple/password-input';
import { Eye, EyeOff } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/password-input.module.css';

export component ControlledVisibility() {
  let visible = track(false);

  <PasswordInput.Root
    class={styles.Root}
    {visible}
    onVisibilityChange={(e) => {
      @visible = e.visible;
    }}
  >
    <PasswordInput.Label class={styles.Label}>
      {'Password is '}
      {@visible ? 'visible' : 'hidden'}
    </PasswordInput.Label>
    <PasswordInput.Control class={styles.Control}>
      <PasswordInput.Input class={styles.Input} />
      <PasswordInput.VisibilityTrigger class={styles.VisibilityTrigger}>
        <PasswordInput.Indicator class={styles.Indicator} fallback={EyeOff}>
          <Eye />
        </PasswordInput.Indicator>
      </PasswordInput.VisibilityTrigger>
    </PasswordInput.Control>
  </PasswordInput.Root>
}

```

### Root Provider

An alternative way to control the password input is to use the `RootProvider` component and the `usePasswordInput` hook.
This way you can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { PasswordInput, usePasswordInput } from 'ark-ripple/password-input';
import { Eye, EyeOff } from 'lucide-ripple';
import styles from 'styles/password-input.module.css';

export component RootProvider() {
  const passwordInput = usePasswordInput();

  <div class="stack">
    <output>
      {'password input is '}
      {@passwordInput.visible ? 'visible' : 'hidden'}
    </output>
    <PasswordInput.RootProvider class={styles.Root} value={passwordInput}>
      <PasswordInput.Label class={styles.Label}>{'Password'}</PasswordInput.Label>
      <PasswordInput.Control class={styles.Control}>
        <PasswordInput.Input class={styles.Input} />
        <PasswordInput.VisibilityTrigger class={styles.VisibilityTrigger}>
          <PasswordInput.Indicator class={styles.Indicator} fallback={EyeOff}>
            <Eye />
          </PasswordInput.Indicator>
        </PasswordInput.VisibilityTrigger>
      </PasswordInput.Control>
    </PasswordInput.RootProvider>
  </div>
}

```

### Field

Here's an example of how to use the `PasswordInput` component with the `Field` component.

**Example: with-field**

```ripple
import { Field } from 'ark-ripple/field';
import { PasswordInput } from 'ark-ripple/password-input';
import { Eye, EyeOff } from 'lucide-ripple';
import field from 'styles/field.module.css';
import styles from 'styles/password-input.module.css';

export component WithField() {
  <Field.Root class={field.Root}>
    <PasswordInput.Root class={styles.Root}>
      <PasswordInput.Label class={styles.Label}>{'Password'}</PasswordInput.Label>
      <PasswordInput.Control class={styles.Control}>
        <PasswordInput.Input class={styles.Input} />
        <PasswordInput.VisibilityTrigger class={styles.VisibilityTrigger}>
          <PasswordInput.Indicator class={styles.Indicator} fallback={EyeOff}>
            <Eye />
          </PasswordInput.Indicator>
        </PasswordInput.VisibilityTrigger>
      </PasswordInput.Control>
    </PasswordInput.Root>
    <Field.HelperText class={field.HelperText}>{'Enter your password'}</Field.HelperText>
    <Field.ErrorText class={field.ErrorText}>{'Password is required'}</Field.ErrorText>
  </Field.Root>
}

```

### Password Managers

Use the `ignorePasswordManager` prop to ignore password managers like 1Password, LastPass, etc. This is useful for
non-login scenarios (e.g., "api keys", "secure notes", "temporary passwords")

> **Currently, this only works for 1Password, LastPass, Bitwarden, Dashlane, and Proton Pass.**

**Example: ignore-password-manager**

```ripple
import { PasswordInput } from 'ark-ripple/password-input';
import { Eye, EyeOff } from 'lucide-ripple';
import styles from 'styles/password-input.module.css';

export component IgnorePasswordManager() {
  <PasswordInput.Root class={styles.Root} ignorePasswordManagers>
    <PasswordInput.Label class={styles.Label}>{'API Key'}</PasswordInput.Label>
    <PasswordInput.Control class={styles.Control}>
      <PasswordInput.Input class={styles.Input} defaultValue="spd_1234567890" />
      <PasswordInput.VisibilityTrigger class={styles.VisibilityTrigger}>
        <PasswordInput.Indicator class={styles.Indicator} fallback={EyeOff}>
          <Eye />
        </PasswordInput.Indicator>
      </PasswordInput.VisibilityTrigger>
    </PasswordInput.Control>
  </PasswordInput.Root>
}

```

### Strength Meter

Combine the `PasswordInput` with a password strength library to show visual feedback about password strength. This
example uses the [`check-password-strength`](https://www.npmjs.com/package/check-password-strength) package to provide
real-time strength validation.

**Example: strength-meter**

```ripple
import { PasswordInput } from 'ark-ripple/password-input';
import { passwordStrength, type Options } from 'check-password-strength';
import { Eye, EyeOff } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/password-input.module.css';

const strengthOptions: Options<string> = [
  { id: 0, value: 'weak', minDiversity: 0, minLength: 0 },
  { id: 1, value: 'medium', minDiversity: 2, minLength: 6 },
  { id: 2, value: 'strong', minDiversity: 4, minLength: 8 },
];

export component StrengthMeter() {
  let password = track('asdfasdf');

  let strength = track(() => {
    if (!@password) return null;
    const { value } = passwordStrength(@password, strengthOptions);
    return value;
  });

  <PasswordInput.Root class={styles.Root}>
    <PasswordInput.Label class={styles.Label}>{'Password'}</PasswordInput.Label>
    <PasswordInput.Control class={styles.Control}>
      <PasswordInput.Input
        class={styles.Input}
        value={password}
        onInput={(e) => {
          @password = e.currentTarget.value;
        }}
        placeholder="Enter your password"
      />
      <PasswordInput.VisibilityTrigger class={styles.VisibilityTrigger}>
        <PasswordInput.Indicator class={styles.Indicator} fallback={EyeOff}>
          <Eye />
        </PasswordInput.Indicator>
      </PasswordInput.VisibilityTrigger>
    </PasswordInput.Control>
    if (@strength) {
      <div class={styles.StrengthMeter}>
        <div class={styles.StrengthBar}>
          <div class={styles.StrengthFill} data-strength={@strength} />
        </div>
        <div class={styles.StrengthLabel}>
          {@strength}
          {' password'}
        </div>
      </div>
    }
  </PasswordInput.Root>
}

```

### Validation

Combine with custom validation logic to show real-time feedback. Use the `invalid` prop to indicate validation errors.

**Example: with-validation**

```ripple
import { PasswordInput } from 'ark-ripple/password-input';
import { Eye, EyeOff } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/password-input.module.css';

export component WithValidation() {
  let password = track('');
  let isValid = track(() => @password.length >= 8);

  <PasswordInput.Root class={styles.Root} invalid={!@isValid && @password.length > 0}>
    <PasswordInput.Label class={styles.Label}>{'Password (min 8 characters)'}</PasswordInput.Label>
    <PasswordInput.Control class={styles.Control}>
      <PasswordInput.Input
        class={styles.Input}
        value={password}
        onInput={(e) => {
          @password = e.target.value;
        }}
        placeholder="Enter your password"
      />
      <PasswordInput.VisibilityTrigger class={styles.VisibilityTrigger}>
        <PasswordInput.Indicator class={styles.Indicator} fallback={EyeOff}>
          <Eye />
        </PasswordInput.Indicator>
      </PasswordInput.VisibilityTrigger>
    </PasswordInput.Control>
    if (@password.length > 0 && !@isValid) {
      <p class={styles.ValidationMessage} data-valid="false">
        {'Password must be at least 8 characters'}
      </p>
    }
    if (@isValid && @password.length > 0) {
      <p class={styles.ValidationMessage} data-valid="true">{'Password is valid'}</p>
    }
  </PasswordInput.Root>
}

```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `autoComplete` | `'current-password' | 'new-password'` | No | The autocomplete attribute for the password input. |
| `defaultVisible` | `boolean` | No | The default visibility of the password input. |
| `disabled` | `boolean` | No | Whether the password input is disabled. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{ input: string; visibilityTrigger: string }>` | No | The ids of the password input parts |
| `ignorePasswordManagers` | `boolean` | No | When `true`, the input will ignore password managers.

**Only works for the following password managers**
- 1Password, LastPass, Bitwarden, Dashlane, Proton Pass |
| `invalid` | `boolean` | No | The invalid state of the password input. |
| `name` | `string` | No | The name of the password input. |
| `onVisibilityChange` | `(details: VisibilityChangeDetails) => void` | No | Function called when the visibility changes. |
| `readOnly` | `boolean` | No | Whether the password input is read only. |
| `required` | `boolean` | No | Whether the password input is required. |
| `translations` | `Partial<{ visibilityTrigger: ((visible: boolean) => string) | undefined }>` | No | The localized messages to use. |
| `visible` | `boolean` | No | Whether the password input is visible. |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | password-input |
| `[data-part]` | root |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]` | Present when invalid |
| `[data-readonly]` | Present when read-only |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | password-input |
| `[data-part]` | control |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]` | Present when invalid |
| `[data-readonly]` | Present when read-only |


**Indicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `fallback` | `string | number | bigint | boolean | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...>` | No | The fallback content to display when the password is not visible. |


**Indicator Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | password-input |
| `[data-part]` | indicator |
| `[data-state]` | "visible" | "hidden" |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]` | Present when invalid |
| `[data-readonly]` | Present when read-only |


**Input Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Input Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | password-input |
| `[data-part]` | input |
| `[data-state]` | "visible" | "hidden" |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]` | Present when invalid |
| `[data-readonly]` | Present when read-only |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | password-input |
| `[data-part]` | label |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]` | Present when invalid |
| `[data-readonly]` | Present when read-only |
| `[data-required]` | Present when required |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UsePasswordInputReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**VisibilityTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**VisibilityTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | password-input |
| `[data-part]` | visibility-trigger |
| `[data-readonly]` | Present when read-only |
| `[data-disabled]` | Present when disabled |
| `[data-state]` | "visible" | "hidden" |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `visible` | `boolean` | Whether the password input is visible. |
| `disabled` | `boolean` | Whether the password input is disabled. |
| `invalid` | `boolean` | Whether the password input is invalid. |
| `focus` | `VoidFunction` | Focus the password input. |
| `setVisible` | `(value: boolean) => void` | Set the visibility of the password input. |
| `toggleVisible` | `VoidFunction` | Toggle the visibility of the password input. |



# Pin Input 



## Anatomy



```tsx
<PinInput.Root>
  <PinInput.Label />
  <PinInput.Control>
    <PinInput.Input />
  </PinInput.Control>
  <PinInput.HiddenInput />
</PinInput.Root>
```

## Examples

**Example: basic**

```ripple
import { PinInput } from 'ark-ripple/pin-input';
import styles from 'styles/pin-input.module.css';

export component Basic() {
  <PinInput.Root class={styles.Root}>
    <PinInput.Label class={styles.Label}>{'Label'}</PinInput.Label>
    <PinInput.Control class={styles.Control}>
      for (const index of [0, 1, 2]; key index) {
        <PinInput.Input class={styles.Input} {index} />
      }
    </PinInput.Control>
    <PinInput.HiddenInput />
  </PinInput.Root>
}

```

### Placeholder

To customize the default pin input placeholder `○` for each input, pass the placeholder prop and set it to your desired
value.

**Example: custom-placeholder**

```ripple
import { PinInput } from 'ark-ripple/pin-input';
import styles from 'styles/pin-input.module.css';

export component CustomPlaceholder() {
  <PinInput.Root class={styles.Root} placeholder="*">
    <PinInput.Label class={styles.Label}>{'Label'}</PinInput.Label>
    <PinInput.Control class={styles.Control}>
      for (const index of [0, 1, 2]; key index) {
        <PinInput.Input class={styles.Input} {index} />
      }
    </PinInput.Control>
    <PinInput.HiddenInput />
  </PinInput.Root>
}

```

### Blur on Complete

By default, the last input maintains focus when filled, and we invoke the `onValueComplete` callback. To blur the last
input when the user completes the input, set the prop `blurOnComplete` to `true`.

**Example: blur-on-complete**

```ripple
import { PinInput } from 'ark-ripple/pin-input';
import styles from 'styles/pin-input.module.css';

export component BlurOnComplete() {
  <PinInput.Root class={styles.Root} blurOnComplete>
    <PinInput.Label class={styles.Label}>{'Label'}</PinInput.Label>
    <PinInput.Control class={styles.Control}>
      for (const index of [0, 1, 2]; key index) {
        <PinInput.Input class={styles.Input} {index} />
      }
    </PinInput.Control>
    <PinInput.HiddenInput />
  </PinInput.Root>
}

```

### 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.

**Example: otp-mode**

```ripple
import { PinInput } from 'ark-ripple/pin-input';
import styles from 'styles/pin-input.module.css';

export component OTPMode() {
  <PinInput.Root class={styles.Root} otp>
    <PinInput.Label class={styles.Label}>{'Label'}</PinInput.Label>
    <PinInput.Control class={styles.Control}>
      for (const index of [0, 1, 2]; key index) {
        <PinInput.Input class={styles.Input} {index} />
      }
    </PinInput.Control>
    <PinInput.HiddenInput />
  </PinInput.Root>
}

```

### Masking

When collecting private or sensitive information using the pin input, you might need to mask the value entered, similar
to `<input type="password"/>`. Pass the `mask` prop to `true`.

**Example: mask**

```ripple
import { PinInput } from 'ark-ripple/pin-input';
import styles from 'styles/pin-input.module.css';

export component Mask() {
  <PinInput.Root class={styles.Root} mask>
    <PinInput.Label class={styles.Label}>{'Label'}</PinInput.Label>
    <PinInput.Control class={styles.Control}>
      for (const index of [0, 1, 2]; key index) {
        <PinInput.Input class={styles.Input} {index} />
      }
    </PinInput.Control>
    <PinInput.HiddenInput />
  </PinInput.Root>
}

```

### Change Events

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".

### Field

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.

**Example: with-field**

```ripple
import { Field } from 'ark-ripple/field';
import { PinInput } from 'ark-ripple/pin-input';
import fieldStyles from 'styles/field.module.css';
import styles from 'styles/pin-input.module.css';

export component WithField() {
  <Field.Root class={fieldStyles.Root}>
    <PinInput.Root class={styles.Root}>
      <PinInput.Label class={styles.Label}>{'Label'}</PinInput.Label>
      <PinInput.Control class={styles.Control}>
        for (const index of [0, 1, 2]; key index) {
          <PinInput.Input class={styles.Input} {index} />
        }
      </PinInput.Control>
      <PinInput.HiddenInput />
    </PinInput.Root>
    <Field.HelperText class={fieldStyles.HelperText}>{'Additional Info'}</Field.HelperText>
    <Field.ErrorText class={fieldStyles.ErrorText}>{'Error Info'}</Field.ErrorText>
  </Field.Root>
}

```

### Root Provider

An alternative way to control the pin input is to use the `RootProvider` component and the `usePinInput` hook. This way
you can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { PinInput, usePinInput } from 'ark-ripple/pin-input';
import styles from 'styles/pin-input.module.css';

export component RootProvider() {
  const pinInput = usePinInput(
    { onValueComplete: (e: PinInput.ValueChangeDetails) => alert(e.valueAsString) },
  );

  <div class="stack">
    <button onClick={() => @pinInput.focus()}>{'Focus'}</button>

    <PinInput.RootProvider value={pinInput} class={styles.Root}>
      <PinInput.Label class={styles.Label}>{'Label'}</PinInput.Label>
      <PinInput.Control class={styles.Control}>
        for (const index of [0, 1, 2]; key index) {
          <PinInput.Input class={styles.Input} {index} />
        }
      </PinInput.Control>
      <PinInput.HiddenInput />
    </PinInput.RootProvider>
  </div>
}

```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `autoFocus` | `boolean` | No | Whether to auto-focus the first input. |
| `blurOnComplete` | `boolean` | No | Whether to blur the input when the value is complete |
| `count` | `number` | No | The number of inputs to render to improve SSR aria attributes.
This will be required in next major version. |
| `defaultValue` | `string[]` | No | The initial value of the the pin input when rendered.
Use when you don't need to control the value of the pin input. |
| `disabled` | `boolean` | No | Whether the inputs are disabled |
| `form` | `string` | No | The associate form of the underlying input element. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{
  root: string
  hiddenInput: string
  label: string
  control: string
  input: (id: string) => string
}>` | No | The ids of the elements in the pin input. Useful for composition. |
| `invalid` | `boolean` | No | Whether the pin input is in the invalid state |
| `mask` | `boolean` | No | If `true`, the input's value will be masked just like `type=password` |
| `name` | `string` | No | The name of the input element. Useful for form submission. |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | Function called on input change |
| `onValueComplete` | `(details: ValueChangeDetails) => void` | No | Function called when all inputs have valid values |
| `onValueInvalid` | `(details: ValueInvalidDetails) => void` | No | Function called when an invalid value is entered |
| `otp` | `boolean` | No | If `true`, the pin input component signals to its fields that they should
use `autocomplete="one-time-code"`. |
| `pattern` | `string` | No | The regular expression that the user-entered input value is checked against. |
| `placeholder` | `string` | No | The placeholder text for the input |
| `readOnly` | `boolean` | No | Whether the pin input is in the valid state |
| `required` | `boolean` | No | Whether the pin input is required |
| `selectOnFocus` | `boolean` | No | Whether to select input value when input is focused |
| `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states |
| `type` | `'numeric' | 'alphanumeric' | 'alphabetic'` | No | The type of value the pin-input should allow |
| `value` | `string[]` | No | The controlled value of the the pin input. |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | pin-input |
| `[data-part]` | root |
| `[data-invalid]` | Present when invalid |
| `[data-disabled]` | Present when disabled |
| `[data-complete]` | Present when the pin-input value is complete |
| `[data-readonly]` | Present when read-only |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**HiddenInput Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Input Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Input Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | pin-input |
| `[data-part]` | input |
| `[data-disabled]` | Present when disabled |
| `[data-complete]` | Present when the input value is complete |
| `[data-index]` | The index of the item |
| `[data-invalid]` | Present when invalid |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | pin-input |
| `[data-part]` | label |
| `[data-invalid]` | Present when invalid |
| `[data-disabled]` | Present when disabled |
| `[data-complete]` | Present when the label value is complete |
| `[data-required]` | Present when required |
| `[data-readonly]` | Present when read-only |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UsePinInputReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `value` | `string[]` | The value of the input as an array of strings. |
| `valueAsString` | `string` | The value of the input as a string. |
| `complete` | `boolean` | Whether all inputs are filled. |
| `count` | `number` | The number of inputs to render |
| `items` | `number[]` | The array of input values. |
| `setValue` | `(value: string[]) => void` | Function to set the value of the inputs. |
| `clearValue` | `VoidFunction` | Function to clear the value of the inputs. |
| `setValueAtIndex` | `(index: number, value: string) => void` | Function to set the value of the input at a specific index. |
| `focus` | `VoidFunction` | Function to focus the pin-input. This will focus the first input. |


## Accessibility

### Keyboard Support

**`ArrowLeft`**
Description: Moves focus to the previous input

**`ArrowRight`**
Description: Moves focus to the next input

**`Backspace`**
Description: Deletes the value in the current input and moves focus to the previous input

**`Delete`**
Description: Deletes the value in the current input

**`Control + V`**
Description: Pastes the value into the input fields


# Popover 



## Anatomy



```tsx
<Popover.Root>
  <Popover.Trigger />
  <Popover.Anchor />
  <Popover.Positioner>
    <Popover.Arrow>
      <Popover.ArrowTip />
    </Popover.Arrow>
    <Popover.Content>
      <Popover.Title />
      <Popover.Description />
      <Popover.CloseTrigger />
    </Popover.Content>
  </Popover.Positioner>
</Popover.Root>
```

## Examples

**Example: basic**

```ripple
import { Popover } from 'ark-ripple/popover';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import styles from 'styles/popover.module.css';

export component Basic() {
  <Popover.Root>
    <Popover.Trigger class={button.Root}>{'Click Me'}</Popover.Trigger>
    <Portal>
      <Popover.Positioner class={styles.Positioner}>
        <Popover.Content class={styles.Content}>
          <Popover.Title class={styles.Title}>{'Favorite Frameworks'}</Popover.Title>
          <Popover.Description class={styles.Description}>
            {'Manage and organize your favorite web frameworks.'}
          </Popover.Description>
        </Popover.Content>
      </Popover.Positioner>
    </Portal>
  </Popover.Root>
}

```

### Controlled

Use the `open` and `onOpenChange` props to control the open state of the popover.

**Example: controlled**

```ripple
import { Popover } from 'ark-ripple/popover';
import { Portal } from 'ark-ripple/portal';
import { track } from 'ripple';
import button from 'styles/button.module.css';
import styles from 'styles/popover.module.css';

export component Controlled() {
  let open = track(false);

  <Popover.Root
    {open}
    onOpenChange={(e) => {
      @open = e.open;
    }}
  >
    <Popover.Trigger class={button.Root}>{'Click Me'}</Popover.Trigger>
    <Portal>
      <Popover.Positioner class={styles.Positioner}>
        <Popover.Content class={styles.Content}>
          <Popover.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Popover.CloseTrigger>
          <Popover.Title class={styles.Title}>{'Team Members'}</Popover.Title>
          <Popover.Description class={styles.Description}>
            {'Invite colleagues to collaborate on this project.'}
          </Popover.Description>
        </Popover.Content>
      </Popover.Positioner>
    </Portal>
  </Popover.Root>
}

```

### Root Provider

An alternative way to control the popover is to use the `RootProvider` component and the `usePopover` hook. This way you
can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { Popover, usePopover } from 'ark-ripple/popover';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import styles from 'styles/popover.module.css';

export component RootProvider() {
  const popover = usePopover(
    {
      positioning: {
        placement: 'bottom-start',
      },
    },
  );

  <div class="stack">
    <div>
      {'Popover is '}
      {@popover.open ? 'open' : 'closed'}
    </div>
    <Popover.RootProvider value={popover}>
      <Popover.Trigger class={button.Root}>{'Toggle Popover'}</Popover.Trigger>
      <Portal>
        <Popover.Positioner class={styles.Positioner}>
          <Popover.Content class={styles.Content}>
            <Popover.Title class={styles.Title}>{'Controlled Externally'}</Popover.Title>
            <Popover.Description class={styles.Description}>
              {'This popover is controlled via the usePopover hook.'}
            </Popover.Description>
          </Popover.Content>
        </Popover.Positioner>
      </Portal>
    </Popover.RootProvider>
  </div>
}

```

### Arrow

Use `Popover.Arrow` and `Popover.ArrowTip` to render an arrow pointing to the trigger.

**Example: arrow**

```ripple
import { Popover } from 'ark-ripple/popover';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import styles from 'styles/popover.module.css';

export component Arrow() {
  <Popover.Root>
    <Popover.Trigger class={button.Root}>{'Click Me'}</Popover.Trigger>
    <Portal>
      <Popover.Positioner class={styles.Positioner}>
        <Popover.Content class={styles.Content}>
          <Popover.Arrow class={styles.Arrow}>
            <Popover.ArrowTip class={styles.ArrowTip} />
          </Popover.Arrow>
          <Popover.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Popover.CloseTrigger>
          <Popover.Title class={styles.Title}>{'Notifications'}</Popover.Title>
          <Popover.Description class={styles.Description}>
            {'You have 3 unread messages in your inbox.'}
          </Popover.Description>
        </Popover.Content>
      </Popover.Positioner>
    </Portal>
  </Popover.Root>
}

```

### Placement

To change the placement of the popover, set the `positioning` prop.

**Example: positioning**

```ripple
import { Popover } from 'ark-ripple/popover';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import styles from 'styles/popover.module.css';

export component Positioning() {
  <Popover.Root
    positioning={{
      placement: 'left-start',
      offset: { mainAxis: 12, crossAxis: 12 },
    }}
  >
    <Popover.Trigger class={button.Root}>{'Click Me'}</Popover.Trigger>
    <Portal>
      <Popover.Positioner class={styles.Positioner}>
        <Popover.Content class={styles.Content}>
          <Popover.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Popover.CloseTrigger>
          <Popover.Title class={styles.Title}>{'Left Placement'}</Popover.Title>
          <Popover.Description class={styles.Description}>
            {'This popover appears on the left with custom offset values.'}
          </Popover.Description>
        </Popover.Content>
      </Popover.Positioner>
    </Portal>
  </Popover.Root>
}

```

### Close Behavior

The popover is designed to close on blur and when the <kbd>esc</kbd> 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 <kbd>esc</kbd> key is pressed, pass the `closeOnEsc` prop and set it to `false`.

**Example: close-behavior**

```ripple
import { Popover } from 'ark-ripple/popover';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import styles from 'styles/popover.module.css';

export component CloseBehavior() {
  <Popover.Root closeOnEscape closeOnInteractOutside>
    <Popover.Trigger class={button.Root}>{'Click Me'}</Popover.Trigger>
    <Portal>
      <Popover.Positioner class={styles.Positioner}>
        <Popover.Content class={styles.Content}>
          <Popover.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Popover.CloseTrigger>
          <Popover.Title class={styles.Title}>{'Quick Actions'}</Popover.Title>
          <Popover.Description class={styles.Description}>
            {'Press Escape or click outside to close this popover.'}
          </Popover.Description>
        </Popover.Content>
      </Popover.Positioner>
    </Portal>
  </Popover.Root>
}

```

### 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.

**Example: modal**

```ripple
import { Popover } from 'ark-ripple/popover';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import styles from 'styles/popover.module.css';

export component Modal() {
  <Popover.Root modal>
    <Popover.Trigger class={button.Root}>{'Click Me'}</Popover.Trigger>
    <Portal>
      <Popover.Positioner class={styles.Positioner}>
        <Popover.Content class={styles.Content}>
          <Popover.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Popover.CloseTrigger>
          <Popover.Title class={styles.Title}>{'Confirm Action'}</Popover.Title>
          <Popover.Description class={styles.Description}>
            {'Focus is trapped inside this modal popover until dismissed.'}
          </Popover.Description>
        </Popover.Content>
      </Popover.Positioner>
    </Portal>
  </Popover.Root>
}

```

### Anchor

Use `Popover.Anchor` to position the popover relative to a different element than the trigger.

**Example: anchor**

```ripple
import { Popover } from 'ark-ripple/popover';
import button from 'styles/button.module.css';
import field from 'styles/field.module.css';
import styles from 'styles/popover.module.css';

export component Anchor() {
  <Popover.Root>
    <div class="hstack">
      <Popover.Trigger class={button.Root}>{'Click Me'}</Popover.Trigger>
      <Popover.Anchor class={styles.Anchor}>
        <input class={field.Input} placeholder="Type here..." />
      </Popover.Anchor>
    </div>

    <Popover.Positioner class={styles.Positioner}>
      <Popover.Content class={styles.Content}>
        <Popover.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Popover.CloseTrigger>
        <Popover.Title class={styles.Title}>{'Title'}</Popover.Title>
        <Popover.Description class={styles.Description}>{'Description'}</Popover.Description>
      </Popover.Content>
    </Popover.Positioner>
  </Popover.Root>
}

```

### Same Width

Use `positioning.sameWidth` to make the popover match the width of its trigger element.

**Example: same-width**

```ripple
import { Popover } from 'ark-ripple/popover';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import styles from 'styles/popover.module.css';

export component SameWidth() {
  <Popover.Root positioning={{ sameWidth: true }}>
    <Popover.Trigger class={button.Root} style={{ minWidth: '200px' }}>
      {'Click Me'}
    </Popover.Trigger>
    <Portal>
      <Popover.Positioner class={styles.Positioner}>
        <Popover.Content class={styles.Content}>
          <Popover.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Popover.CloseTrigger>
          <Popover.Title class={styles.Title}>{'Matched Width'}</Popover.Title>
          <Popover.Description class={styles.Description}>
            {'This popover matches the width of its trigger element.'}
          </Popover.Description>
        </Popover.Content>
      </Popover.Positioner>
    </Portal>
  </Popover.Root>
}

```

### Dialog Integration

When rendering a popover inside a dialog, you have two options for proper layering:

1. **Keep the Portal with `lazyMount` and `unmountOnExit`** - This ensures the popover is properly unmounted when the
   dialog closes, preventing stale DOM nodes.

2. **Remove the Portal** - Render the popover inline within the dialog content. This works well but may have z-index
   considerations.

**Example: with-dialog**

```ripple
import { Dialog } from 'ark-ripple/dialog';
import { Popover } from 'ark-ripple/popover';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import dialog from 'styles/dialog.module.css';
import styles from 'styles/popover.module.css';

export component WithDialog() {
  <Dialog.Root>
    <Dialog.Trigger class={button.Root}>{'Open Dialog'}</Dialog.Trigger>
    <Portal>
      <Dialog.Backdrop class={dialog.Backdrop} />
      <Dialog.Positioner class={dialog.Positioner}>
        <Dialog.Content class={dialog.Content}>
          <Dialog.CloseTrigger class={dialog.CloseTrigger}>{'✕'}</Dialog.CloseTrigger>
          <Dialog.Title class={dialog.Title}>{'Edit Profile'}</Dialog.Title>
          <Dialog.Description class={dialog.Description}>
            {'Update your profile information below.'}
          </Dialog.Description>
          <div class={dialog.Body}>
            <Popover.Root lazyMount unmountOnExit>
              <Popover.Trigger class={button.Root}>{'More Options'}</Popover.Trigger>
              <Portal>
                <Popover.Positioner class={styles.Positioner}>
                  <Popover.Content class={styles.Content}>
                    <Popover.Arrow class={styles.Arrow}>
                      <Popover.ArrowTip class={styles.ArrowTip} />
                    </Popover.Arrow>
                    <Popover.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Popover.CloseTrigger>
                    <Popover.Title class={styles.Title}>{'Additional Settings'}</Popover.Title>
                    <Popover.Description class={styles.Description}>
                      {'This popover renders correctly above the dialog.'}
                    </Popover.Description>
                  </Popover.Content>
                </Popover.Positioner>
              </Portal>
            </Popover.Root>
          </div>
        </Dialog.Content>
      </Dialog.Positioner>
    </Portal>
  </Dialog.Root>
}

```

### Nested

Popovers can be nested within each other. Each nested popover maintains its own open state and positioning.

**Example: nested**

```ripple
import { Popover } from 'ark-ripple/popover';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import styles from 'styles/popover.module.css';

export component Nested() {
  <Popover.Root>
    <Popover.Trigger class={button.Root}>{'Click Me'}</Popover.Trigger>
    <Portal>
      <Popover.Positioner class={styles.Positioner}>
        <Popover.Content class={styles.Content}>
          <Popover.Title class={styles.Title}>{'Settings'}</Popover.Title>
          <Popover.Description class={styles.Description}>
            {'Manage your preferences and account settings.'}
          </Popover.Description>
          <Popover.Root lazyMount unmountOnExit positioning={{ placement: 'right' }}>
            <Popover.Trigger class={button.Root}>{'Advanced'}</Popover.Trigger>
            <Portal>
              <Popover.Positioner class={styles.Positioner}>
                <Popover.Content class={styles.Content}>
                  <Popover.Title class={styles.Title}>{'Advanced Settings'}</Popover.Title>
                  <Popover.Description class={styles.Description}>
                    {'Configure advanced options for power users.'}
                  </Popover.Description>
                </Popover.Content>
              </Popover.Positioner>
            </Portal>
          </Popover.Root>
        </Popover.Content>
      </Popover.Positioner>
    </Portal>
  </Popover.Root>
}

```

## Guides

### Available Size

The following css variables are exposed to the `Popover.Positioner` which you can use to style the `Popover.Content`

```css
/* width of the popover trigger */
--reference-width: <pixel-value>;
/* width of the available viewport */
--available-width: <pixel-value>;
/* height of the available viewport */
--available-height: <pixel-value>;
```

For example, if you want to make sure the maximum height doesn't exceed the available height, use the following css:

```css
[data-scope='popover'][data-part='content'] {
  max-height: calc(var(--available-height) - 100px);
}
```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `autoFocus` | `boolean` | No | Whether to automatically set focus on the first focusable
content within the popover when opened. |
| `closeOnEscape` | `boolean` | No | Whether to close the popover when the escape key is pressed. |
| `closeOnInteractOutside` | `boolean` | No | Whether to close the popover when the user clicks outside of the popover. |
| `defaultOpen` | `boolean` | No | The initial open state of the popover when rendered.
Use when you don't need to control the open state of the popover. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{
  anchor: string
  trigger: string
  content: string
  title: string
  description: string
  closeTrigger: string
  positioner: string
  arrow: string
}>` | No | The ids of the elements in the popover. Useful for composition. |
| `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame |
| `initialFocusEl` | `() => HTMLElement | null` | No | The element to focus on when the popover is opened. |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `modal` | `boolean` | No | Whether the popover should be modal. When set to `true`:
- interaction with outside elements will be disabled
- only popover content will be visible to screen readers
- scrolling is blocked
- focus is trapped within the popover |
| `onEscapeKeyDown` | `(event: KeyboardEvent) => void` | No | Function called when the escape key is pressed |
| `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state |
| `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component |
| `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component |
| `onOpenChange` | `(details: OpenChangeDetails) => void` | No | Function invoked when the popover opens or closes |
| `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component |
| `onRequestDismiss` | `(event: LayerDismissEvent) => void` | No | Function called when this layer is closed due to a parent layer being closed |
| `open` | `boolean` | No | The controlled open state of the popover |
| `persistentElements` | `(() => Element | null)[]` | No | Returns the persistent elements that:
- should not have pointer-events disabled
- should not trigger the dismiss event |
| `portalled` | `boolean` | No | Whether the popover is portalled. This will proxy the tabbing behavior regardless of the DOM position
of the popover content. |
| `positioning` | `PositioningOptions` | No | The user provided options used to position the popover content |
| `present` | `boolean` | No | Whether the node is present (controlled by the user) |
| `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


**Anchor Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Arrow Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Arrow CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--arrow-size` | The size of the arrow |
| `--arrow-size-half` | Half the size of the arrow |
| `--arrow-background` | Use this variable to style the arrow background |
| `--arrow-offset` | The offset position of the arrow |


**ArrowTip Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**CloseTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | popover |
| `[data-part]` | content |
| `[data-state]` | "open" | "closed" |
| `[data-nested]` | popover |
| `[data-has-nested]` | popover |
| `[data-expanded]` | Present when expanded |
| `[data-placement]` | The placement of the content |


**Content CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--layer-index` | The index of the dismissable in the layer stack |
| `--nested-layer-count` | The number of nested popovers |


**Description Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Indicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Indicator Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | popover |
| `[data-part]` | indicator |
| `[data-state]` | "open" | "closed" |


**Positioner Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Positioner CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--reference-width` | The width of the reference element |
| `--reference-height` | The height of the root |
| `--available-width` | The available width in viewport |
| `--available-height` | The available height in viewport |
| `--x` | The x position for transform |
| `--y` | The y position for transform |
| `--z-index` | The z-index value |
| `--transform-origin` | The transform origin for animations |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UsePopoverReturn` | Yes |  |
| `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state |
| `present` | `boolean` | No | Whether the node is present (controlled by the user) |
| `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


**Title Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | popover |
| `[data-part]` | trigger |
| `[data-placement]` | The placement of the trigger |
| `[data-state]` | "open" | "closed" |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `portalled` | `boolean` | Whether the popover is portalled. |
| `open` | `boolean` | Whether the popover is open |
| `setOpen` | `(open: boolean) => void` | Function to open or close the popover |
| `reposition` | `(options?: Partial<PositioningOptions>) => void` | Function to reposition the popover |


## Accessibility

### Keyboard Support

**`Space`**
Description: Opens/closes the popover.

**`Enter`**
Description: Opens/closes the popover.

**`Tab`**
Description: <span>Moves focus to the next focusable element within the content.<br /><strong>Note:</strong> If there are no focusable elements, focus is moved to the next focusable element after the trigger.</span>

**`Shift + Tab`**
Description: <span>Moves focus to the previous focusable element within the content<br /><strong>Note:</strong> If there are no focusable elements, focus is moved to the trigger.</span>

**`Esc`**
Description: <span>Closes the popover and moves focus to the trigger.</span>


# QR Code 



## Anatomy



```tsx
<QrCode.Root>
  <QrCode.Frame>
    <QrCode.Pattern />
  </QrCode.Frame>
  <QrCode.Overlay />
  <QrCode.DownloadTrigger />
</QrCode.Root>
```

## Examples

**Example: basic**

```ripple
import { QrCode } from 'ark-ripple/qr-code';
import styles from 'styles/qr-code.module.css';

export component Basic() {
  <QrCode.Root class={styles.Root} defaultValue="http://ark-ui.com">
    <QrCode.Frame class={styles.Frame}>
      <QrCode.Pattern class={styles.Pattern} />
    </QrCode.Frame>
  </QrCode.Root>
}

```

### 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.

**Example: overlay**

```ripple
import { QrCode } from 'ark-ripple/qr-code';
import styles from 'styles/qr-code.module.css';

export component Overlay() {
  <QrCode.Root class={styles.Root} defaultValue="http://ark-ui.com" encoding={{ ecc: 'H' }}>
    <QrCode.Frame class={styles.Frame}>
      <QrCode.Pattern class={styles.Pattern} />
    </QrCode.Frame>
    <QrCode.Overlay class={styles.Overlay}>
      <img src="https://ark-ui.com/icon-192.png" alt="Ark UI Logo" />
    </QrCode.Overlay>
  </QrCode.Root>
}

```

### 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

**Example: error-correction**

```ripple
import { QrCode } from 'ark-ripple/qr-code';
import { RadioGroup } from 'ark-ripple/radio-group';
import { track } from 'ripple';
import styles from 'styles/qr-code.module.css';
import radio from 'styles/radio-group.module.css';

export component ErrorCorrection() {
  let errorLevel = track('L');

  <div class="stack">
    <QrCode.Root
      class={styles.Root}
      defaultValue="http://ark-ui.com"
      encoding={{ ecc: errorLevel }}
    >
      <QrCode.Frame class={styles.Frame}>
        <QrCode.Pattern class={styles.Pattern} />
      </QrCode.Frame>
    </QrCode.Root>
    <RadioGroup.Root
      class={radio.Root}
      defaultValue="L"
      orientation="horizontal"
      onValueChange={(e) => {
        @errorLevel = e.value;
      }}
    >
      <div class="hstack">
        for (const level of ['L', 'M', 'Q', 'H']; key level) {
          <RadioGroup.Item class={radio.Item} value={level}>
            <RadioGroup.ItemControl class={radio.ItemControl} />
            <RadioGroup.ItemText class={radio.ItemText}>{level}</RadioGroup.ItemText>
            <RadioGroup.ItemHiddenInput />
          </RadioGroup.Item>
        }
      </div>
    </RadioGroup.Root>
  </div>
}

```

### Root Provider

An alternative way to control the QR code is to use the `RootProvider` component and the `useQrCode` hook. This way you
can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { QrCode, useQrCode } from 'ark-ripple/qr-code';
import styles from 'styles/qr-code.module.css';

export component RootProvider() {
  const qrCode = useQrCode({ value: 'http://ark-ui.com' });

  <div class="stack">
    <QrCode.RootProvider class={styles.Root} value={qrCode}>
      <QrCode.Frame class={styles.Frame}>
        <QrCode.Pattern class={styles.Pattern} />
      </QrCode.Frame>
    </QrCode.RootProvider>
    <output>{@qrCode.value}</output>
  </div>
}

```

### Download

Use the `QrCode.DownloadTrigger` component to allow users to download the QR code as an image. Specify the `fileName`
and `mimeType` props for the downloaded file.

**Example: download**

```ripple
import { QrCode } from 'ark-ripple/qr-code';
import button from 'styles/button.module.css';
import styles from 'styles/qr-code.module.css';

export component Download() {
  <QrCode.Root class={styles.Root} defaultValue="http://ark-ui.com">
    <QrCode.Frame class={styles.Frame}>
      <QrCode.Pattern class={styles.Pattern} />
    </QrCode.Frame>
    <QrCode.DownloadTrigger class={button.Root} fileName="qr-code.png" mimeType="image/png">
      {'Download'}
    </QrCode.DownloadTrigger>
  </QrCode.Root>
}

```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `defaultValue` | `string` | No | The initial value to encode when rendered.
Use when you don't need to control the value of the qr code. |
| `encoding` | `QrCodeGenerateOptions` | No | The qr code encoding options. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{ root: string; frame: string }>` | No | The element ids. |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | Callback fired when the value changes. |
| `pixelSize` | `number` | No | The pixel size of the qr code. |
| `value` | `string` | No | The controlled value to encode. |


**Root CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--qrcode-pixel-size` | The size of the Root |
| `--qrcode-width` | The width of the Root |
| `--qrcode-height` | The height of the Root |


**DownloadTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `fileName` | `string` | Yes | The name of the file. |
| `mimeType` | `DataUrlType` | Yes | The mime type of the image. |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `quality` | `number` | No | The quality of the image. |


**Frame Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Overlay Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Pattern Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseQrCodeReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `value` | `string` | The value to encode. |
| `setValue` | `(value: string) => void` | Set the value to encode. |
| `getDataUrl` | `(type: DataUrlType, quality?: number) => Promise<string>` | Returns the data URL of the qr code. |



# Radio Group 



## Anatomy



```tsx
<RadioGroup.Root>
  <RadioGroup.Label />
  <RadioGroup.Indicator />
  <RadioGroup.Item>
    <RadioGroup.ItemControl />
    <RadioGroup.ItemText />
    <RadioGroup.ItemHiddenInput />
  </RadioGroup.Item>
</RadioGroup.Root>
```

## Examples

**Example: basic**

```ripple
import { RadioGroup } from 'ark-ripple/radio-group';
import styles from 'styles/radio-group.module.css';

const frameworks = ['React', 'Solid', 'Vue'];

export component Basic() {
  <RadioGroup.Root class={styles.Root} defaultValue="React">
    <RadioGroup.Label class={styles.Label}>{'Framework'}</RadioGroup.Label>
    for (const framework of frameworks; key framework) {
      <RadioGroup.Item class={styles.Item} value={framework}>
        <RadioGroup.ItemControl class={styles.ItemControl} />
        <RadioGroup.ItemText class={styles.ItemText}>{framework}</RadioGroup.ItemText>
        <RadioGroup.ItemHiddenInput />
      </RadioGroup.Item>
    }
  </RadioGroup.Root>
}

```

### 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.

**Example: initial-value**

```ripple
import { RadioGroup } from 'ark-ripple/radio-group';
import styles from 'styles/radio-group.module.css';

const frameworks = ['React', 'Solid', 'Vue'];

export component InitialValue() {
  <RadioGroup.Root class={styles.Root} defaultValue="Solid">
    <RadioGroup.Label class={styles.Label}>{'Framework'}</RadioGroup.Label>
    for (const framework of frameworks; key framework) {
      <RadioGroup.Item class={styles.Item} value={framework}>
        <RadioGroup.ItemControl class={styles.ItemControl} />
        <RadioGroup.ItemText class={styles.ItemText}>{framework}</RadioGroup.ItemText>
        <RadioGroup.ItemHiddenInput />
      </RadioGroup.Item>
    }
  </RadioGroup.Root>
}

```

### Controlled

For a controlled Radio Group, the state is managed using the `value` prop, and updates when the `onValueChange` event
handler is called:

**Example: controlled**

```ripple
import { RadioGroup } from 'ark-ripple/radio-group';
import { track } from 'ripple';
import styles from 'styles/radio-group.module.css';

const frameworks = ['React', 'Solid', 'Vue'];

export component Controlled() {
  let value = track<string | null>(null);

  <RadioGroup.Root
    class={styles.Root}
    {value}
    onValueChange={(e) => {
      @value = e.value;
    }}
  >
    <RadioGroup.Label class={styles.Label}>{'Framework'}</RadioGroup.Label>
    for (const framework of frameworks; key framework) {
      <RadioGroup.Item class={styles.Item} value={framework}>
        <RadioGroup.ItemControl class={styles.ItemControl} />
        <RadioGroup.ItemText class={styles.ItemText}>{framework}</RadioGroup.ItemText>
        <RadioGroup.ItemHiddenInput />
      </RadioGroup.Item>
    }
  </RadioGroup.Root>
}

```

### Root Provider

An alternative way to control the radio group is to use the `RootProvider` component and the `useRadioGroup` hook. This
way you can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { RadioGroup, useRadioGroup } from 'ark-ripple/radio-group';
import button from 'styles/button.module.css';
import styles from 'styles/radio-group.module.css';

const frameworks = ['React', 'Solid', 'Vue'];

export component RootProvider() {
  const radioGroup = useRadioGroup({ defaultValue: 'React' });

  <div class="stack">
    <RadioGroup.RootProvider class={styles.Root} value={radioGroup}>
      <RadioGroup.Label class={styles.Label}>{'Framework'}</RadioGroup.Label>
      for (const framework of frameworks; key framework) {
        <RadioGroup.Item class={styles.Item} value={framework}>
          <RadioGroup.ItemControl class={styles.ItemControl} />
          <RadioGroup.ItemText class={styles.ItemText}>{framework}</RadioGroup.ItemText>
          <RadioGroup.ItemHiddenInput />
        </RadioGroup.Item>
      }
    </RadioGroup.RootProvider>
    <button class={button.Root} onClick={() => @radioGroup.setValue('Solid')}>
      {'Set to Solid'}
    </button>
  </div>
}

```

### Disabled

To make a radio group disabled, set the `disabled` prop to `true`.

**Example: disabled**

```ripple
import { RadioGroup } from 'ark-ripple/radio-group';
import styles from 'styles/radio-group.module.css';

const frameworks = ['React', 'Solid', 'Vue'];

export component Disabled() {
  <RadioGroup.Root class={styles.Root} defaultValue="React" disabled>
    <RadioGroup.Label class={styles.Label}>{'Framework'}</RadioGroup.Label>
    for (const framework of frameworks; key framework) {
      <RadioGroup.Item class={styles.Item} value={framework}>
        <RadioGroup.ItemControl class={styles.ItemControl} />
        <RadioGroup.ItemText class={styles.ItemText}>{framework}</RadioGroup.ItemText>
        <RadioGroup.ItemHiddenInput />
      </RadioGroup.Item>
    }
  </RadioGroup.Root>
}

```

## Guides

### asChild

The `RadioGroup.Item` component renders as a `label` element by default. This ensures proper form semantics and
accessibility, as radio groups are form controls that require labels to provide meaningful context for users.

When using the `asChild` prop, you must **render a `label` element** as the direct child of `RadioGroup.Item` to
maintain valid HTML structure and accessibility compliance.

```tsx
// INCORRECT usage ❌
<RadioGroup.Item asChild>
  <div>
    <RadioGroup.ItemHiddenInput />
    <RadioGroup.ItemText>
      <RadioGroup.ItemControl />
    </RadioGroup.ItemText>
  </div>
</RadioGroup.Item>

// CORRECT usage ✅
<RadioGroup.Item asChild>
  <label>
    <RadioGroup.ItemHiddenInput />
    <RadioGroup.ItemText>
      <RadioGroup.ItemControl />
    </RadioGroup.ItemText>
  </label>
</RadioGroup.Item>
```

### Hidden Input

The `RadioGroup.ItemHiddenInput` component renders a hidden HTML input element that enables proper form submission and
integration with native form behaviors. This component is essential for the radio group to function correctly as it:

- Provides the underlying input element that browsers use for form submission
- Enables integration with form libraries and validation systems
- Ensures the radio group works with native form reset functionality

```tsx
// INCORRECT usage ❌
<RadioGroup.Item>
  <RadioGroup.ItemText>
    <RadioGroup.ItemControl />
  </RadioGroup.ItemText>
</RadioGroup.Item>

// CORRECT usage ✅
<RadioGroup.Item>
  <RadioGroup.ItemHiddenInput />
  <RadioGroup.ItemText>
    <RadioGroup.ItemControl />
  </RadioGroup.ItemText>
</RadioGroup.Item>
```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `defaultValue` | `string` | No | The initial value of the checked radio when rendered.
Use when you don't need to control the value of the radio group. |
| `disabled` | `boolean` | No | If `true`, the radio group will be disabled |
| `form` | `string` | No | The associate form of the underlying input. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{
  root: string
  label: string
  indicator: string
  item: (value: string) => string
  itemLabel: (value: string) => string
  itemControl: (value: string) => string
  itemHiddenInput: (value: string) => string
}>` | No | The ids of the elements in the radio. Useful for composition. |
| `invalid` | `boolean` | No | If `true`, the radio group is marked as invalid. |
| `name` | `string` | No | The name of the input fields in the radio
(Useful for form submission). |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | Function called once a radio is checked |
| `orientation` | `'horizontal' | 'vertical'` | No | Orientation of the radio group |
| `readOnly` | `boolean` | No | Whether the radio group is read-only |
| `required` | `boolean` | No | If `true`, the radio group is marked as required. |
| `value` | `string` | No | The controlled value of the radio group |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | radio-group |
| `[data-part]` | root |
| `[data-orientation]` | The orientation of the radio-group |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]` | Present when invalid |
| `[data-required]` | Present when required |


**Indicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Indicator Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | radio-group |
| `[data-part]` | indicator |
| `[data-disabled]` | Present when disabled |
| `[data-orientation]` | The orientation of the indicator |


**Indicator CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--transition-property` | The transition property value for the Indicator |
| `--left` | The left position value |
| `--top` | The top position value |
| `--width` | The width of the element |
| `--height` | The height of the element |


**ItemControl Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemControl Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | radio-group |
| `[data-part]` | item-control |
| `[data-active]` | Present when active or pressed |


**ItemHiddenInput Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `string` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `disabled` | `boolean` | No |  |
| `invalid` | `boolean` | No |  |


**ItemText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | radio-group |
| `[data-part]` | label |
| `[data-orientation]` | The orientation of the label |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]` | Present when invalid |
| `[data-required]` | Present when required |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseRadioGroupReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `value` | `string` | The current value of the radio group |
| `setValue` | `(value: string) => void` | Function to set the value of the radio group |
| `clearValue` | `VoidFunction` | Function to clear the value of the radio group |
| `focus` | `VoidFunction` | Function to focus the radio group |
| `getItemState` | `(props: ItemProps) => ItemState` | Returns the state details of a radio input |


## Accessibility

Complies with the [Radio WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/).

### Keyboard Support

**`Tab`**
Description: Moves focus to either the checked radio item or the first radio item in the group.

**`Space`**
Description: When focus is on an unchecked radio item, checks it.

**`ArrowDown`**
Description: Moves focus and checks the next radio item in the group.

**`ArrowRight`**
Description: Moves focus and checks the next radio item in the group.

**`ArrowUp`**
Description: Moves focus to the previous radio item in the group.

**`ArrowLeft`**
Description: Moves focus to the previous radio item in the group.


# Rating Group 



## Anatomy



```tsx
<RatingGroup.Root>
  <RatingGroup.Label />
  <RatingGroup.Control>
    <RatingGroup.Item>
      <RatingGroup.ItemContext />
    </RatingGroup.Item>
    <RatingGroup.HiddenInput />
  </RatingGroup.Control>
</RatingGroup.Root>
```

## Examples

**Example: basic**

```ripple
import { RatingGroup } from 'ark-ripple/rating-group';
import { Star } from 'lucide-ripple';
import styles from 'styles/rating-group.module.css';

export component Basic() {
  <RatingGroup.Root class={styles.Root} defaultValue={3}>
    <RatingGroup.Label class={styles.Label}>{'Label'}</RatingGroup.Label>
    <RatingGroup.Control class={styles.Control}>
      <RatingGroup.Context>
        component children({ context }) {
          for (const item of @context.items; key item) {
            <RatingGroup.Item class={styles.Item} index={item}>
              <RatingGroup.ItemContext>
                component children({ context }) {
                  <span
                    class={styles.ItemIndicator}
                    data-highlighted={@context.highlighted ? '' : undefined}
                  >
                    <Star data-bg="" />
                    <Star data-fg="" fill="currentColor" />
                  </span>
                }
              </RatingGroup.ItemContext>
            </RatingGroup.Item>
          }
        }
      </RatingGroup.Context>
      <RatingGroup.HiddenInput />
    </RatingGroup.Control>
  </RatingGroup.Root>
}

```

### Controlled

When using the `RatingGroup` component, you can use the `value` and `onValueChange` props to control the state.

**Example: controlled**

```ripple
import { RatingGroup } from 'ark-ripple/rating-group';
import { Star } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/rating-group.module.css';

export component Controlled() {
  let value = track(0);

  <RatingGroup.Root
    class={styles.Root}
    {value}
    onValueChange={(details) => {
      @value = details.value;
    }}
  >
    <RatingGroup.Label class={styles.Label}>{'Label'}</RatingGroup.Label>
    <RatingGroup.Control class={styles.Control}>
      <RatingGroup.Context>
        component children({ context }) {
          for (const item of @context.items; key item) {
            <RatingGroup.Item class={styles.Item} index={item}>
              <RatingGroup.ItemContext>
                component children({ context }) {
                  <span
                    class={styles.ItemIndicator}
                    data-half={@context.half ? '' : undefined}
                    data-highlighted={@context.highlighted ? '' : undefined}
                  >
                    <Star data-bg="" />
                    <Star data-fg="" fill="currentColor" />
                  </span>
                }
              </RatingGroup.ItemContext>
            </RatingGroup.Item>
          }
        }
      </RatingGroup.Context>
      <RatingGroup.HiddenInput />
    </RatingGroup.Control>
  </RatingGroup.Root>
}

```

### Root Provider

An alternative way to control the rating group is to use the `RootProvider` component and the `useRatingGroup` hook.
This way you can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { RatingGroup, useRatingGroup } from 'ark-ripple/rating-group';
import { Star } from 'lucide-ripple';
import styles from 'styles/rating-group.module.css';

export component RootProvider() {
  const ratingGroup = useRatingGroup({ count: 5, defaultValue: 3 });

  <div class="stack">
    <output>
      {'value: '}
      {@ratingGroup.value}
    </output>
    <RatingGroup.RootProvider class={styles.Root} value={ratingGroup}>
      <RatingGroup.Label class={styles.Label}>{'Label'}</RatingGroup.Label>
      <RatingGroup.Control class={styles.Control}>
        <RatingGroup.Context>
          component children({ context }) {
            for (const item of @context.items; key item) {
              <RatingGroup.Item class={styles.Item} index={item}>
                <RatingGroup.ItemContext>
                  component children({ context }) {
                    <span
                      class={styles.ItemIndicator}
                      data-highlighted={@context.highlighted ? '' : undefined}
                    >
                      <Star data-bg="" />
                      <Star data-fg="" fill="currentColor" />
                    </span>
                  }
                </RatingGroup.ItemContext>
              </RatingGroup.Item>
            }
          }
        </RatingGroup.Context>
        <RatingGroup.HiddenInput />
      </RatingGroup.Control>
    </RatingGroup.RootProvider>
  </div>
}

```

### Field

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.

**Example: with-field**

```ripple
import { Field } from 'ark-ripple/field';
import { RatingGroup } from 'ark-ripple/rating-group';
import { Star } from 'lucide-ripple';
import field from 'styles/field.module.css';
import styles from 'styles/rating-group.module.css';

export component WithField() {
  <Field.Root class={field.Root}>
    <RatingGroup.Root class={styles.Root} count={5} defaultValue={3}>
      <RatingGroup.Label class={styles.Label}>{'Label'}</RatingGroup.Label>
      <RatingGroup.Control class={styles.Control}>
        <RatingGroup.Context>
          component children({ context }) {
            for (const item of @context.items; key item) {
              <RatingGroup.Item class={styles.Item} index={item}>
                <RatingGroup.ItemContext>
                  component children({ context }) {
                    <span
                      class={styles.ItemIndicator}
                      data-highlighted={@context.highlighted ? '' : undefined}
                    >
                      <Star data-bg="" />
                      <Star data-fg="" fill="currentColor" />
                    </span>
                  }
                </RatingGroup.ItemContext>
              </RatingGroup.Item>
            }
          }
        </RatingGroup.Context>
        <RatingGroup.HiddenInput />
      </RatingGroup.Control>
    </RatingGroup.Root>
    <Field.HelperText class={field.HelperText}>{'Additional Info'}</Field.HelperText>
    <Field.ErrorText class={field.ErrorText}>{'Error Info'}</Field.ErrorText>
  </Field.Root>
}

```

### Half Rating

Allow `0.5` value steps by setting the `allowHalf` prop to `true`. Ensure to render the correct icon if the `half` value
is set in the Rating components render callback.

**Example: half-star**

```ripple
import { RatingGroup } from 'ark-ripple/rating-group';
import { Star } from 'lucide-ripple';
import styles from 'styles/rating-group.module.css';

export component HalfStar() {
  <RatingGroup.Root class={styles.Root} defaultValue={2.5} allowHalf>
    <RatingGroup.Label class={styles.Label}>{'Label'}</RatingGroup.Label>
    <RatingGroup.Control class={styles.Control}>
      <RatingGroup.Context>
        component children({ context }) {
          for (const item of @context.items; key item) {
            <RatingGroup.Item class={styles.Item} index={item}>
              <RatingGroup.ItemContext>
                component children({ context }) {
                  <span
                    class={styles.ItemIndicator}
                    data-half={@context.half ? '' : undefined}
                    data-highlighted={@context.highlighted ? '' : undefined}
                  >
                    <Star data-bg="" />
                    <Star data-fg="" fill="currentColor" />
                  </span>
                }
              </RatingGroup.ItemContext>
            </RatingGroup.Item>
          }
        }
      </RatingGroup.Context>
      <RatingGroup.HiddenInput />
    </RatingGroup.Control>
  </RatingGroup.Root>
}

```

### 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.

**Example: form-usage**

```ripple
import { RatingGroup } from 'ark-ripple/rating-group';
import { Star } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/rating-group.module.css';

export component FormUsage() {
  <form
    class="stack"
    onSubmit={(e) => {
      e.preventDefault();
      const formData = new FormData(e.currentTarget);
      alert(`Rating value: ${formData.get('review')}`);
    }}
  >
    <RatingGroup.Root class={styles.Root} name="review" defaultValue={3}>
      <RatingGroup.Label class={styles.Label}>{'Label'}</RatingGroup.Label>
      <RatingGroup.Control class={styles.Control}>
        <RatingGroup.Context>
          component children({ context }) {
            for (const item of @context.items; key item) {
              <RatingGroup.Item class={styles.Item} index={item}>
                <RatingGroup.ItemContext>
                  component children({ context }) {
                    <span
                      class={styles.ItemIndicator}
                      data-highlighted={@context.highlighted ? '' : undefined}
                    >
                      <Star data-bg="" />
                      <Star data-fg="" fill="currentColor" />
                    </span>
                  }
                </RatingGroup.ItemContext>
              </RatingGroup.Item>
            }
          }
        </RatingGroup.Context>
        <RatingGroup.HiddenInput />
      </RatingGroup.Control>
    </RatingGroup.Root>
    <button type="submit" class={button.Root}>{'Submit'}</button>
  </form>
}

```

### Disabled

To make the rating group disabled, set the `disabled` prop to `true`.

**Example: disabled**

```ripple
import { RatingGroup } from 'ark-ripple/rating-group';
import { Star } from 'lucide-ripple';
import styles from 'styles/rating-group.module.css';

export component Disabled() {
  <RatingGroup.Root class={styles.Root} defaultValue={3} disabled>
    <RatingGroup.Label class={styles.Label}>{'Label'}</RatingGroup.Label>
    <RatingGroup.Control class={styles.Control}>
      <RatingGroup.Context>
        component children({ context }) {
          for (const item of @context.items; key item) {
            <RatingGroup.Item class={styles.Item} index={item}>
              <RatingGroup.ItemContext>
                component children({ context }) {
                  <span
                    class={styles.ItemIndicator}
                    data-highlighted={@context.highlighted ? '' : undefined}
                  >
                    <Star data-bg="" />
                    <Star data-fg="" fill="currentColor" />
                  </span>
                }
              </RatingGroup.ItemContext>
            </RatingGroup.Item>
          }
        }
      </RatingGroup.Context>
      <RatingGroup.HiddenInput />
    </RatingGroup.Control>
  </RatingGroup.Root>
}

```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `allowHalf` | `boolean` | No | Whether to allow half stars. |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `autoFocus` | `boolean` | No | Whether to autofocus the rating. |
| `count` | `number` | No | The total number of ratings. |
| `defaultValue` | `number` | No | The initial value of the rating when rendered.
Use when you don't need to control the value of the rating. |
| `disabled` | `boolean` | No | Whether the rating is disabled. |
| `form` | `string` | No | The associate form of the underlying input element. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{
  root: string
  label: string
  hiddenInput: string
  control: string
  item: (id: string) => string
}>` | No | The ids of the elements in the rating. Useful for composition. |
| `name` | `string` | No | The name attribute of the rating element (used in forms). |
| `onHoverChange` | `(details: HoverChangeDetails) => void` | No | Function to be called when the rating value is hovered. |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | Function to be called when the rating value changes. |
| `readOnly` | `boolean` | No | Whether the rating is readonly. |
| `required` | `boolean` | No | Whether the rating is required. |
| `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states |
| `value` | `number` | No | The controlled value of the rating |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | rating-group |
| `[data-part]` | control |
| `[data-readonly]` | Present when read-only |
| `[data-disabled]` | Present when disabled |


**HiddenInput Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Item Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | rating-group |
| `[data-part]` | item |
| `[data-disabled]` | Present when disabled |
| `[data-readonly]` | Present when read-only |
| `[data-checked]` | Present when checked |
| `[data-highlighted]` | Present when highlighted |
| `[data-half]` |  |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | rating-group |
| `[data-part]` | label |
| `[data-disabled]` | Present when disabled |
| `[data-required]` | Present when required |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseRatingGroupReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `setValue` | `(value: number) => void` | Sets the value of the rating group |
| `clearValue` | `VoidFunction` | Clears the value of the rating group |
| `hovering` | `boolean` | Whether the rating group is being hovered |
| `value` | `number` | The current value of the rating group |
| `hoveredValue` | `number` | The value of the currently hovered rating |
| `count` | `number` | The total number of ratings |
| `items` | `number[]` | The array of rating values. Returns an array of numbers from 1 to the max value. |
| `getItemState` | `(props: ItemProps) => ItemState` | Returns the state of a rating item |


## Accessibility

### Keyboard Support

**`ArrowRight`**
Description: Moves focus to the next star, increasing the rating value based on the `allowHalf` property.

**`ArrowLeft`**
Description: Moves focus to the previous star, decreasing the rating value based on the `allowHalf` property.

**`Enter`**
Description: Selects the focused star in the rating group.


# Scroll Area 



## Anatomy



```tsx
<ScrollArea.Root>
  <ScrollArea.Viewport>
    <ScrollArea.Content />
  </ScrollArea.Viewport>
  <ScrollArea.Scrollbar>
    <ScrollArea.Thumb />
  </ScrollArea.Scrollbar>
  <ScrollArea.Corner />
</ScrollArea.Root>
```

## Required style

It's important to note that the scroll area requires the following styles on the `ScrollArea.Viewport` element to hide
the native scrollbar:

```css
[data-scope='scroll-area'][data-part='viewport'] {
  scrollbar-width: none;
  &::-webkit-scrollbar {
    display: none;
  }
}
```

## Examples

### Basic

Create a basic scrollable area with custom scrollbar.

**Example: basic**

```ripple
import { ScrollArea } from 'ark-ripple/scroll-area';
import styles from 'styles/scroll-area.module.css';

export component Basic() {
  <ScrollArea.Root class={styles.Root}>
    <ScrollArea.Viewport class={styles.Viewport}>
      <ScrollArea.Content class={styles.Content}>
        <p class={styles.Paragraph}>
          {'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.'}
        </p>
      </ScrollArea.Content>
    </ScrollArea.Viewport>
    <ScrollArea.Scrollbar orientation="vertical" class={styles.Scrollbar}>
      <ScrollArea.Thumb class={styles.Thumb} />
    </ScrollArea.Scrollbar>
    <ScrollArea.Corner class={styles.Corner} />
  </ScrollArea.Root>
}

```

### Horizontal

Configure the scroll area for horizontal scrolling only.

**Example: horizontal**

```ripple
import { ScrollArea } from 'ark-ripple/scroll-area';
import styles from 'styles/scroll-area.module.css';

export component Horizontal() {
  <ScrollArea.Root class={styles.Root} style="height: auto">
    <ScrollArea.Viewport class={styles.Viewport}>
      <ScrollArea.Content class={styles.Content}>
        <p class={styles.Paragraph} style="width: 50vw">
          {'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.'}
        </p>
      </ScrollArea.Content>
    </ScrollArea.Viewport>
    <ScrollArea.Scrollbar orientation="horizontal" class={styles.Scrollbar}>
      <ScrollArea.Thumb class={styles.Thumb} />
    </ScrollArea.Scrollbar>
    <ScrollArea.Corner class={styles.Corner} />
  </ScrollArea.Root>
}

```

### Both Directions

Enable scrolling in both horizontal and vertical directions.

**Example: both-directions**

```ripple
import { ScrollArea } from 'ark-ripple/scroll-area';
import styles from 'styles/scroll-area.module.css';

export component BothDirections() {
  <ScrollArea.Root class={styles.Root}>
    <ScrollArea.Viewport class={styles.Viewport}>
      <ScrollArea.Content class={styles.Content}>
        <p class={styles.Paragraph} style="width: 50vw">
          {'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.'}
        </p>
      </ScrollArea.Content>
    </ScrollArea.Viewport>
    <ScrollArea.Scrollbar orientation="vertical" class={styles.Scrollbar}>
      <ScrollArea.Thumb class={styles.Thumb} />
    </ScrollArea.Scrollbar>
    <ScrollArea.Scrollbar orientation="horizontal" class={styles.Scrollbar}>
      <ScrollArea.Thumb class={styles.Thumb} />
    </ScrollArea.Scrollbar>
    <ScrollArea.Corner class={styles.Corner} />
  </ScrollArea.Root>
}

```

### Nested

Scroll areas can be nested within each other for complex layouts.

**Example: nested**

```ripple
import { ScrollArea } from 'ark-ripple/scroll-area';
import styles from 'styles/scroll-area.module.css';

export component Nested() {
  <ScrollArea.Root class={styles.Root} style="height: 12rem">
    <ScrollArea.Viewport class={styles.Viewport}>
      <ScrollArea.Content class={styles.Content}>
        <p class={styles.Paragraph}>
          {'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.'}
        </p>
        <ScrollArea.Root class={styles.Root} style="height: 8rem; width: 100%">
          <ScrollArea.Viewport class={styles.Viewport}>
            <ScrollArea.Content class={styles.Content}>
              <p class={styles.Paragraph}>
                {'This is a nested scroll area. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.'}
              </p>
            </ScrollArea.Content>
          </ScrollArea.Viewport>
          <ScrollArea.Scrollbar orientation="vertical" class={styles.Scrollbar}>
            <ScrollArea.Thumb class={styles.Thumb} />
          </ScrollArea.Scrollbar>
          <ScrollArea.Corner class={styles.Corner} />
        </ScrollArea.Root>
      </ScrollArea.Content>
    </ScrollArea.Viewport>
    <ScrollArea.Scrollbar orientation="vertical" class={styles.Scrollbar}>
      <ScrollArea.Thumb class={styles.Thumb} />
    </ScrollArea.Scrollbar>
    <ScrollArea.Corner class={styles.Corner} />
  </ScrollArea.Root>
}

```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ids` | `Partial<{ root: string; viewport: string; content: string; scrollbar: string; thumb: string }>` | No | The ids of the scroll area elements |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | root |
| `[data-overflow-x]` | Present when the content overflows the x-axis |
| `[data-overflow-y]` | Present when the content overflows the y-axis |


**Root CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--corner-width` | The width of the Root |
| `--corner-height` | The height of the Root |
| `--thumb-width` | The width of the slider thumb |
| `--thumb-height` | The height of the slider thumb |


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | content |
| `[data-overflow-x]` | Present when the content overflows the x-axis |
| `[data-overflow-y]` | Present when the content overflows the y-axis |


**Corner Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Corner Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | corner |
| `[data-hover]` | Present when hovered |
| `[data-state]` | "hidden" | "visible" |
| `[data-overflow-x]` | Present when the content overflows the x-axis |
| `[data-overflow-y]` | Present when the content overflows the y-axis |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseScrollAreaReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Scrollbar Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `orientation` | `Orientation` | No |  |


**Scrollbar Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | scrollbar |
| `[data-orientation]` | The orientation of the scrollbar |
| `[data-scrolling]` | Present when scrolling |
| `[data-hover]` | Present when hovered |
| `[data-dragging]` | Present when in the dragging state |
| `[data-overflow-x]` | Present when the content overflows the x-axis |
| `[data-overflow-y]` | Present when the content overflows the y-axis |


**Thumb Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Thumb Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | thumb |
| `[data-orientation]` | The orientation of the thumb |
| `[data-hover]` | Present when hovered |
| `[data-dragging]` | Present when in the dragging state |


**Viewport Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Viewport Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | viewport |
| `[data-at-top]` | Present when scrolled to the top edge |
| `[data-at-bottom]` | Present when scrolled to the bottom edge |
| `[data-at-left]` | Present when scrolled to the left edge |
| `[data-at-right]` | Present when scrolled to the right edge |
| `[data-overflow-x]` | Present when the content overflows the x-axis |
| `[data-overflow-y]` | Present when the content overflows the y-axis |


**Viewport CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--scroll-area-overflow-x-start` | The distance from the horizontal start edge in pixels |
| `--scroll-area-overflow-x-end` | The distance from the horizontal end edge in pixels |
| `--scroll-area-overflow-y-start` | The distance from the vertical start edge in pixels |
| `--scroll-area-overflow-y-end` | The distance from the vertical end edge in pixels |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `isAtTop` | `boolean` | Whether the scroll area is at the top |
| `isAtBottom` | `boolean` | Whether the scroll area is at the bottom |
| `isAtLeft` | `boolean` | Whether the scroll area is at the left |
| `isAtRight` | `boolean` | Whether the scroll area is at the right |
| `hasOverflowX` | `boolean` | Whether the scroll area has horizontal overflow |
| `hasOverflowY` | `boolean` | Whether the scroll area has vertical overflow |
| `getScrollProgress` | `() => Point` | Get the scroll progress as values between 0 and 1 |
| `scrollToEdge` | `(details: ScrollToEdgeDetails) => void` | Scroll to the edge of the scroll area |
| `scrollTo` | `(details: ScrollToDetails) => void` | Scroll to specific coordinates |
| `getScrollbarState` | `(props: ScrollbarProps) => ScrollbarState` | Returns the state of the scrollbar |



# Segment Group 



## Anatomy



```tsx
<SegmentGroup.Root>
  <SegmentGroup.Indicator />
  <SegmentGroup.Item>
    <SegmentGroup.ItemText />
    <SegmentGroup.ItemControl />
    <SegmentGroup.ItemHiddenInput />
  </SegmentGroup.Item>
</SegmentGroup.Root>
```

## Examples

**Example: basic**

```ripple
import { SegmentGroup } from 'ark-ripple/segment-group';
import styles from 'styles/segment-group.module.css';

const frameworks = ['React', 'Solid', 'Vue'];

export component Basic() {
  <SegmentGroup.Root class={styles.Root} defaultValue="React">
    <SegmentGroup.Indicator class={styles.Indicator} />
    for (const framework of frameworks; key framework) {
      <SegmentGroup.Item class={styles.Item} value={framework}>
        <SegmentGroup.ItemText class={styles.ItemText}>{framework}</SegmentGroup.ItemText>
        <SegmentGroup.ItemControl class={styles.ItemControl} />
        <SegmentGroup.ItemHiddenInput />
      </SegmentGroup.Item>
    }
  </SegmentGroup.Root>
}

```

### Controlled

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:

**Example: controlled**

```ripple
import { SegmentGroup } from 'ark-ripple/segment-group';
import { track } from 'ripple';
import styles from 'styles/segment-group.module.css';

const frameworks = ['React', 'Solid', 'Vue'];

export component Controlled() {
  let value = track<string | null>(null);

  <SegmentGroup.Root
    class={styles.Root}
    {value}
    onValueChange={(e) => {
      @value = e.value;
    }}
  >
    <SegmentGroup.Indicator class={styles.Indicator} />
    for (const framework of frameworks; key framework) {
      <SegmentGroup.Item class={styles.Item} value={framework}>
        <SegmentGroup.ItemText class={styles.ItemText}>{framework}</SegmentGroup.ItemText>
        <SegmentGroup.ItemControl class={styles.ItemControl} />
        <SegmentGroup.ItemHiddenInput />
      </SegmentGroup.Item>
    }
  </SegmentGroup.Root>
}

```

### Root Provider

An alternative way to control the segment group is to use the `RootProvider` component and the `useSegmentGroup` hook.
This way you can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { SegmentGroup, useSegmentGroup } from 'ark-ripple/segment-group';
import styles from 'styles/segment-group.module.css';

const frameworks = ['React', 'Solid', 'Vue'];

export component RootProvider() {
  const segmentGroup = useSegmentGroup({ defaultValue: 'React' });

  <div class="stack">
    <SegmentGroup.RootProvider class={styles.Root} value={segmentGroup}>
      <SegmentGroup.Indicator class={styles.Indicator} />
      for (const framework of frameworks; key framework) {
        <SegmentGroup.Item class={styles.Item} value={framework}>
          <SegmentGroup.ItemText class={styles.ItemText}>{framework}</SegmentGroup.ItemText>
          <SegmentGroup.ItemControl class={styles.ItemControl} />
          <SegmentGroup.ItemHiddenInput />
        </SegmentGroup.Item>
      }
    </SegmentGroup.RootProvider>
    <output>
      {'selected: '}
      {@segmentGroup.value}
    </output>
  </div>
}

```

### Disabled

To disable a segment, simply pass the `disabled` prop to the `SegmentGroup.Item` component:

**Example: disabled**

```ripple
import { SegmentGroup } from 'ark-ripple/segment-group';
import styles from 'styles/segment-group.module.css';

const frameworks = ['React', 'Solid', 'Vue'];

export component Disabled() {
  <SegmentGroup.Root class={styles.Root} defaultValue="React">
    <SegmentGroup.Indicator class={styles.Indicator} />
    for (const framework of frameworks; key framework) {
      <SegmentGroup.Item class={styles.Item} value={framework} disabled={framework === 'Vue'}>
        <SegmentGroup.ItemText class={styles.ItemText}>{framework}</SegmentGroup.ItemText>
        <SegmentGroup.ItemControl class={styles.ItemControl} />
        <SegmentGroup.ItemHiddenInput />
      </SegmentGroup.Item>
    }
  </SegmentGroup.Root>
}

```

## API Reference

<ComponentTypes id="radio-group" replace={{ 'radio-group': 'segment-group', 'radio group': 'segment group' }} />

## 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



```tsx
<Select.Root>
  <Select.Label />
  <Select.Control>
    <Select.Trigger>
      <Select.ValueText />
    </Select.Trigger>
    <Select.ClearTrigger />
    <Select.Indicator />
  </Select.Control>
  <Select.Positioner>
    <Select.Content>
      <Select.ItemGroup>
        <Select.ItemGroupLabel />
        <Select.Item>
          <Select.ItemText />
          <Select.ItemIndicator />
        </Select.Item>
      </Select.ItemGroup>
    </Select.Content>
  </Select.Positioner>
  <Select.HiddenSelect />
</Select.Root>
```

## Examples

**Example: basic**

```ripple
import { Portal } from 'ark-ripple/portal';
import { Select, createListCollection } from 'ark-ripple/select';
import { ChevronsUpDown, X } from 'lucide-ripple';
import styles from 'styles/select.module.css';

const frameworks = createListCollection(
  {
    items: [
      { label: 'React', value: 'react' },
      { label: 'Solid', value: 'solid' },
      { label: 'Vue', value: 'vue' },
      { label: 'Svelte', value: 'svelte' },
    ],
  },
);

export component Basic() {
  <Select.Root class={styles.Root} collection={frameworks}>
    <Select.Label class={styles.Label}>{'Framework'}</Select.Label>
    <Select.Control class={styles.Control}>
      <Select.Trigger class={styles.Trigger}>
        <Select.ValueText class={styles.ValueText} placeholder="Select" />
      </Select.Trigger>
      <div class={styles.Indicators}>
        <Select.ClearTrigger class={styles.ClearTrigger}>
          <X />
        </Select.ClearTrigger>
        <Select.Indicator class={styles.Indicator}>
          <ChevronsUpDown />
        </Select.Indicator>
      </div>
    </Select.Control>
    <Portal>
      <Select.Positioner>
        <Select.Content class={styles.Content}>
          <Select.ItemGroup class={styles.ItemGroup}>
            <Select.ItemGroupLabel class={styles.ItemGroupLabel}>
              {'Frameworks'}
            </Select.ItemGroupLabel>
            for (const item of frameworks.items; key item.value) {
              <Select.Item class={styles.Item} {item}>
                <Select.ItemText class={styles.ItemText}>{item.label}</Select.ItemText>
                <Select.ItemIndicator class={styles.ItemIndicator}>{'✓'}</Select.ItemIndicator>
              </Select.Item>
            }
          </Select.ItemGroup>
        </Select.Content>
      </Select.Positioner>
    </Portal>
    <Select.HiddenSelect />
  </Select.Root>
}

```

### Controlled

Use the `value` and `onValueChange` props to control the selected items.

**Example: controlled**

```ripple
import { Portal } from 'ark-ripple/portal';
import { track } from 'ripple';
import { Select, createListCollection } from 'ark-ripple/select';
import { ChevronsUpDown, X } from 'lucide-ripple';
import styles from 'styles/select.module.css';

interface Item {
  label: string;
  value: string;
  disabled?: boolean | undefined;
}

const collection = createListCollection<Item>(
  {
    items: [
      { label: 'React', value: 'react' },
      { label: 'Solid', value: 'solid' },
      { label: 'Vue', value: 'vue' },
      { label: 'Svelte', value: 'svelte', disabled: true },
    ],
  },
);

export component Controlled() {
  let value = track<string[]>([]);
  const setValue = (v: string[]) => {
    @value = v;
  };

  <Select.Root
    class={styles.Root}
    {collection}
    {value}
    onValueChange={(e: any) => setValue(e.value)}
  >
    <Select.Label class={styles.Label}>{'Framework'}</Select.Label>
    <Select.Control class={styles.Control}>
      <Select.Trigger class={styles.Trigger}>
        <Select.ValueText class={styles.ValueText} placeholder="Select a Framework" />
      </Select.Trigger>
      <div class={styles.Indicators}>
        <Select.ClearTrigger class={styles.ClearTrigger}>
          <X />
        </Select.ClearTrigger>
        <Select.Indicator class={styles.Indicator}>
          <ChevronsUpDown />
        </Select.Indicator>
      </div>
    </Select.Control>
    <Portal>
      <Select.Positioner>
        <Select.Content class={styles.Content}>
          <Select.ItemGroup class={styles.ItemGroup}>
            <Select.ItemGroupLabel class={styles.ItemGroupLabel}>
              {'Frameworks'}
            </Select.ItemGroupLabel>
            for (const item of collection.items; key item.value) {
              <Select.Item class={styles.Item} {item}>
                <Select.ItemText class={styles.ItemText}>{item.label}</Select.ItemText>
                <Select.ItemIndicator class={styles.ItemIndicator}>{'✓'}</Select.ItemIndicator>
              </Select.Item>
            }
          </Select.ItemGroup>
        </Select.Content>
      </Select.Positioner>
    </Portal>
    <Select.HiddenSelect />
  </Select.Root>
}

```

### Root Provider

An alternative way to control the select is to use the `RootProvider` component and the `useSelect` hook. This way you
can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { Portal } from 'ark-ripple/portal';
import { Select, createListCollection, useSelect } from 'ark-ripple/select';
import { ChevronsUpDown, X } from 'lucide-ripple';
import styles from 'styles/select.module.css';

const frameworks = createListCollection(
  {
    items: [
      { label: 'React', value: 'react' },
      { label: 'Solid', value: 'solid' },
      { label: 'Vue', value: 'vue' },
      { label: 'Svelte', value: 'svelte' },
    ],
  },
);

export component RootProvider() {
  const select = useSelect({ collection: frameworks });

  <div>
    <output>
      {'selected: '}
      {JSON.stringify(@select.value)}
    </output>

    <Select.RootProvider class={styles.Root} value={select}>
      <Select.Label class={styles.Label}>{'Framework'}</Select.Label>
      <Select.Control class={styles.Control}>
        <Select.Trigger class={styles.Trigger}>
          <Select.ValueText class={styles.ValueText} placeholder="Select a Framework" />
        </Select.Trigger>
        <div class={styles.Indicators}>
          <Select.ClearTrigger class={styles.ClearTrigger}>
            <X />
          </Select.ClearTrigger>
          <Select.Indicator class={styles.Indicator}>
            <ChevronsUpDown />
          </Select.Indicator>
        </div>
      </Select.Control>
      <Portal>
        <Select.Positioner>
          <Select.Content class={styles.Content}>
            <Select.ItemGroup class={styles.ItemGroup}>
              <Select.ItemGroupLabel class={styles.ItemGroupLabel}>
                {'Frameworks'}
              </Select.ItemGroupLabel>
              for (const item of frameworks.items; key item.value) {
                <Select.Item class={styles.Item} {item}>
                  <Select.ItemText class={styles.ItemText}>{item.label}</Select.ItemText>
                  <Select.ItemIndicator class={styles.ItemIndicator}>{'✓'}</Select.ItemIndicator>
                </Select.Item>
              }
            </Select.ItemGroup>
          </Select.Content>
        </Select.Positioner>
      </Portal>
      <Select.HiddenSelect />
    </Select.RootProvider>
  </div>
}

```

### Multiple

To enable `multiple` item selection:

**Example: multiple**

```ripple
import { Portal } from 'ark-ripple/portal';
import { Select, createListCollection } from 'ark-ripple/select';
import { ChevronsUpDown, X } from 'lucide-ripple';
import styles from 'styles/select.module.css';

const frameworks = createListCollection(
  {
    items: [
      { label: 'React', value: 'react' },
      { label: 'Solid', value: 'solid' },
      { label: 'Vue', value: 'vue' },
      { label: 'Svelte', value: 'svelte', disabled: true },
    ],
  },
);

export component Multiple() {
  <Select.Root class={styles.Root} collection={frameworks} multiple>
    <Select.Label class={styles.Label}>{'Framework'}</Select.Label>
    <Select.Control class={styles.Control}>
      <Select.Trigger class={styles.Trigger}>
        <Select.ValueText class={styles.ValueText} placeholder="Select" />
      </Select.Trigger>
      <div class={styles.Indicators}>
        <Select.ClearTrigger class={styles.ClearTrigger}>
          <X />
        </Select.ClearTrigger>
        <Select.Indicator class={styles.Indicator}>
          <ChevronsUpDown />
        </Select.Indicator>
      </div>
    </Select.Control>
    <Portal>
      <Select.Positioner>
        <Select.Content class={styles.Content}>
          <Select.ItemGroup class={styles.ItemGroup}>
            <Select.ItemGroupLabel class={styles.ItemGroupLabel}>
              {'Frameworks'}
            </Select.ItemGroupLabel>
            for (const item of frameworks.items; key item.value) {
              <Select.Item class={styles.Item} {item}>
                <Select.ItemText class={styles.ItemText}>{item.label}</Select.ItemText>
                <Select.ItemIndicator class={styles.ItemIndicator}>{'✓'}</Select.ItemIndicator>
              </Select.Item>
            }
          </Select.ItemGroup>
        </Select.Content>
      </Select.Positioner>
    </Portal>
    <Select.HiddenSelect />
  </Select.Root>
}

```

### Grouping

Grouping related options can be useful for organizing options into categories.

- Use the `groupBy` prop to configure the grouping of the items.
- Use the `collection.group()` method to get the grouped items.
- Use the `Select.ItemGroup` and `Select.ItemGroupLabel` components to render the grouped items.

**Example: grouping**

```ripple
import { Portal } from 'ark-ripple/portal';
import { Select, createListCollection } from 'ark-ripple/select';
import { ChevronsUpDown, X } from 'lucide-ripple';
import styles from 'styles/select.module.css';

const frameworks = createListCollection(
  {
    items: [
      { label: 'React', value: 'react', type: 'JS' },
      { label: 'Solid', value: 'solid', type: 'JS' },
      { label: 'Vue', value: 'vue', type: 'JS' },
      { label: 'Panda', value: 'panda', type: 'CSS' },
      { label: 'Tailwind', value: 'tailwind', type: 'CSS' },
    ],
    groupBy: (item: any) => item.type,
  },
);

export component Grouping() {
  <Select.Root class={styles.Root} collection={frameworks}>
    <Select.Label class={styles.Label}>{'Framework'}</Select.Label>
    <Select.Control class={styles.Control}>
      <Select.Trigger class={styles.Trigger}>
        <Select.ValueText class={styles.ValueText} placeholder="Select a Framework" />
      </Select.Trigger>
      <div class={styles.Indicators}>
        <Select.ClearTrigger class={styles.ClearTrigger}>
          <X />
        </Select.ClearTrigger>
        <Select.Indicator class={styles.Indicator}>
          <ChevronsUpDown />
        </Select.Indicator>
      </div>
    </Select.Control>
    <Portal>
      <Select.Positioner>
        <Select.Content class={styles.Content}>
          for (const [type, group] of frameworks.group(); key type) {
            <Select.ItemGroup class={styles.ItemGroup}>
              <Select.ItemGroupLabel class={styles.ItemGroupLabel}>{type}</Select.ItemGroupLabel>
              for (const item of group; key item.value) {
                <Select.Item class={styles.Item} {item}>
                  <Select.ItemText class={styles.ItemText}>{item.label}</Select.ItemText>
                  <Select.ItemIndicator class={styles.ItemIndicator}>{'✓'}</Select.ItemIndicator>
                </Select.Item>
              }
            </Select.ItemGroup>
          }
        </Select.Content>
      </Select.Positioner>
    </Portal>
    <Select.HiddenSelect />
  </Select.Root>
}

```

### Field

Use `Field` to manage form state, ARIA labels, helper text, and error text.

**Example: with-field**

```ripple
import { Select, createListCollection } from 'ark-ripple/select';
import { Field } from 'ark-ripple/field';
import { ChevronsUpDown } from 'lucide-ripple';
import field from 'styles/field.module.css';
import styles from 'styles/select.module.css';

const collection = createListCollection({ items: ['React', 'Solid', 'Vue', 'Svelte'] });

export component WithField() {
  <Field.Root class={field.Root}>
    <Select.Root {collection} class={styles.Root}>
      <Select.Label class={styles.Label}>{'Label'}</Select.Label>
      <Select.Control class={styles.Control}>
        <Select.Trigger class={styles.Trigger}>
          <Select.ValueText class={styles.ValueText} placeholder="Select a Framework" />
          <Select.Indicator class={styles.Indicator}>
            <ChevronsUpDown />
          </Select.Indicator>
        </Select.Trigger>
      </Select.Control>
      <Select.Positioner>
        <Select.Content class={styles.Content}>
          for (const item of collection.items; key item) {
            <Select.Item class={styles.Item} {item}>
              <Select.ItemText class={styles.ItemText}>{item}</Select.ItemText>
              <Select.ItemIndicator class={styles.ItemIndicator}>{'✓'}</Select.ItemIndicator>
            </Select.Item>
          }
        </Select.Content>
      </Select.Positioner>
      <Select.HiddenSelect />
    </Select.Root>
    <Field.HelperText class={field.HelperText}>{'Additional Info'}</Field.HelperText>
    <Field.ErrorText class={field.ErrorText}>{'Error Info'}</Field.ErrorText>
  </Field.Root>
}

```

### Form Usage

Here's an example of integrating the `Select` component with a form library.

**Example: form-library**

```ripple
import { Portal } from 'ark-ripple/portal';
import { track } from 'ripple';
import { Select, createListCollection } from 'ark-ripple/select';
import { ChevronsUpDown, X } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/select.module.css';

const collection = createListCollection(
  {
    items: ['React', 'Solid', 'Vue', 'Svelte'],
  },
);

export component FormLibrary() {
  let value = track<string[]>(['React']);
  const setValue = (v: string[]) => {
    @value = v;
  };

  const handleSubmit = (e: any) => {
    e.preventDefault();
    window.alert(JSON.stringify(new FormData(e.currentTarget).getAll('framework')));
  };

  // TODO: Add form library instead of native form
  <form onSubmit={handleSubmit}>
    <Select.Root
      class={styles.Root}
      {collection}
      {value}
      onValueChange={(e: any) => setValue(e.value)}
    >
      <Select.Label class={styles.Label}>{'Framework'}</Select.Label>
      <Select.HiddenSelect />
      <Select.Control class={styles.Control}>
        <Select.Trigger class={styles.Trigger}>
          <Select.ValueText class={styles.ValueText} placeholder="Select a Framework" />
        </Select.Trigger>
        <div class={styles.Indicators}>
          <Select.ClearTrigger class={styles.ClearTrigger}>
            <X />
          </Select.ClearTrigger>
          <Select.Indicator class={styles.Indicator}>
            <ChevronsUpDown />
          </Select.Indicator>
        </div>
      </Select.Control>
      <Portal>
        <Select.Positioner>
          <Select.Content class={styles.Content}>
            <Select.ItemGroup class={styles.ItemGroup}>
              <Select.ItemGroupLabel class={styles.ItemGroupLabel}>
                {'Frameworks'}
              </Select.ItemGroupLabel>
              for (const item of collection.items; key item) {
                <Select.Item class={styles.Item} {item}>
                  <Select.ItemText class={styles.ItemText}>{item}</Select.ItemText>
                  <Select.ItemIndicator class={styles.ItemIndicator}>{'✓'}</Select.ItemIndicator>
                </Select.Item>
              }
            </Select.ItemGroup>
          </Select.Content>
        </Select.Positioner>
      </Portal>
    </Select.Root>
    <button class={button.Root} style="margin-top: 1rem" type="submit">{'Submit'}</button>
  </form>
}

```

### Async Loading

Here's an example of how to load the items asynchronously when the select is opened.

**Example: async**

```ripple
import { Portal } from 'ark-ripple/portal';
import { track } from 'ripple';
import { Select, createListCollection } from 'ark-ripple/select';
import { ChevronsUpDown } from 'lucide-ripple';
import styles from 'styles/select.module.css';

function loadData() {
  return new Promise<string[]>((resolve) => {
    setTimeout(() => resolve(['React', 'Solid', 'Vue', 'Svelte', 'Angular', 'Ember']), 500);
  });
}

export component Async() {
  let data = track<string[] | null>(null);
  let loading = track(false);
  let error = track<Error | null>(null);

  const collection = track(() => createListCollection<string>({ items: @data ?? [] }));

  const setData = (v: string[] | null) => {
    @data = v;
  };
  const setLoading = (v: boolean) => {
    @loading = v;
  };
  const setError = (v: Error | null) => {
    @error = v;
  };

  const handleOpenChange = (details: any) => {
    if (details.open && @data === null) {
      setLoading(true);
      setError(null);
      loadData().then((data) => setData(data)).catch((err) => setError(err)).finally(
        () => setLoading(false),
      );
    }
  };

  <Select.Root class={styles.Root} {collection} onOpenChange={handleOpenChange}>
    <Select.Label class={styles.Label}>{'Framework'}</Select.Label>
    <Select.Control class={styles.Control}>
      <Select.Trigger class={styles.Trigger}>
        <Select.ValueText class={styles.ValueText} placeholder="Select" />
        <Select.Indicator class={styles.Indicator}>
          <ChevronsUpDown />
        </Select.Indicator>
      </Select.Trigger>
    </Select.Control>
    <Portal>
      <Select.Positioner>
        <Select.Content class={styles.Content}>
          if (@loading) {
            <div class={styles.Item}>{'Loading...'}</div>
          } else if (@error) {
            <div class={styles.Item}>
              {'Error: '}
              {@error.message}
            </div>
          } else {
            for (const item of @collection.items; key item) {
              <Select.Item class={styles.Item} {item}>
                <Select.ItemText class={styles.ItemText}>{item}</Select.ItemText>
                <Select.ItemIndicator class={styles.ItemIndicator}>{'✓'}</Select.ItemIndicator>
              </Select.Item>
            }
          }
        </Select.Content>
      </Select.Positioner>
    </Portal>
    <Select.HiddenSelect />
  </Select.Root>
}

```

### Lazy Mount

Use `lazyMount` and `unmountOnExit` to control when content is mounted, improving performance.

**Example: lazy-mount**

```ripple
import { Portal } from 'ark-ripple/portal';
import { Select, createListCollection } from 'ark-ripple/select';
import { ChevronsUpDown } from 'lucide-ripple';
import styles from 'styles/select.module.css';

const collection = createListCollection(
  {
    items: ['React', 'Solid', 'Vue', 'Svelte', 'Angular', 'Alpine'],
  },
);

export component LazyMount() {
  <Select.Root class={styles.Root} {collection} lazyMount unmountOnExit>
    <Select.Label class={styles.Label}>{'Framework'}</Select.Label>
    <Select.Control class={styles.Control}>
      <Select.Trigger class={styles.Trigger}>
        <Select.ValueText class={styles.ValueText} placeholder="Select a Framework" />
        <Select.Indicator class={styles.Indicator}>
          <ChevronsUpDown />
        </Select.Indicator>
      </Select.Trigger>
      <Select.ClearTrigger class={styles.ClearTrigger}>{'Clear'}</Select.ClearTrigger>
    </Select.Control>
    <Portal>
      <Select.Positioner>
        <Select.Content class={styles.Content}>
          <Select.ItemGroup class={styles.ItemGroup}>
            <Select.ItemGroupLabel class={styles.ItemGroupLabel}>
              {'Frameworks'}
            </Select.ItemGroupLabel>
            for (const item of collection.items; key item) {
              <Select.Item class={styles.Item} {item}>
                <Select.ItemText class={styles.ItemText}>{item}</Select.ItemText>
                <Select.ItemIndicator class={styles.ItemIndicator}>{'✓'}</Select.ItemIndicator>
              </Select.Item>
            }
          </Select.ItemGroup>
        </Select.Content>
      </Select.Positioner>
    </Portal>
    <Select.HiddenSelect />
  </Select.Root>
}

```

### Select on Highlight

Here's an example of automatically selecting items when they are highlighted (hovered or navigated to with keyboard).

**Example: select-on-highlight**

```ripple
import { Portal } from 'ark-ripple/portal';
import { Select, createListCollection, useSelect } from 'ark-ripple/select';
import { ChevronsUpDown } from 'lucide-ripple';
import styles from 'styles/select.module.css';

const collection = createListCollection(
  {
    items: ['React', 'Solid', 'Vue', 'Svelte'],
  },
);

export component SelectOnHighlight() {
  const select = useSelect(
    {
      collection,
      onHighlightChange(details: any) {
        if (details.highlightedValue) {
          @select.selectValue(details.highlightedValue);
        }
      },
    },
  );

  <Select.RootProvider class={styles.Root} value={select}>
    <Select.Label class={styles.Label}>{'Framework'}</Select.Label>
    <Select.Control class={styles.Control}>
      <Select.Trigger class={styles.Trigger}>
        <Select.ValueText class={styles.ValueText} placeholder="Select a Framework" />
        <Select.Indicator class={styles.Indicator}>
          <ChevronsUpDown />
        </Select.Indicator>
      </Select.Trigger>
      <Select.ClearTrigger class={styles.ClearTrigger}>{'Clear'}</Select.ClearTrigger>
    </Select.Control>
    <Portal>
      <Select.Positioner>
        <Select.Content class={styles.Content}>
          <Select.ItemGroup class={styles.ItemGroup}>
            <Select.ItemGroupLabel class={styles.ItemGroupLabel}>
              {'Frameworks'}
            </Select.ItemGroupLabel>
            for (const item of collection.items; key item) {
              <Select.Item class={styles.Item} {item}>
                <Select.ItemText class={styles.ItemText}>{item}</Select.ItemText>
                <Select.ItemIndicator class={styles.ItemIndicator}>{'✓'}</Select.ItemIndicator>
              </Select.Item>
            }
          </Select.ItemGroup>
        </Select.Content>
      </Select.Positioner>
    </Portal>
    <Select.HiddenSelect />
  </Select.RootProvider>
}

```

### Max Selection

Here's an example of limiting the number of items that can be selected in a multiple select.

**Example: max-selected**

```ripple
import { Portal } from 'ark-ripple/portal';
import { track } from 'ripple';
import { Select, createListCollection } from 'ark-ripple/select';
import { ChevronsUpDown, X } from 'lucide-ripple';
import styles from 'styles/select.module.css';

const items = ['React', 'Solid', 'Vue', 'Svelte'];
const MAX_SELECTION = 2;
const hasReachedMax = (value: string[]) => value.length >= MAX_SELECTION;

export component MaxSelected() {
  let value = track<string[]>([]);
  const setValue = (v: string[]) => {
    @value = v;
  };

  const collection = track(
    () => createListCollection(
      {
        items: items.map(
          (item) => ({
            label: item,
            value: item,
            disabled: hasReachedMax(@value) && !@value.includes(item),
          }),
        ),
      },
    ),
  );

  const handleValueChange = (details: Select.ValueChangeDetails) => {
    if (hasReachedMax(@value) && details.value.length > @value.length) return;
    setValue(details.value);
  };

  <Select.Root class={styles.Root} multiple {value} {collection} onValueChange={handleValueChange}>
    <Select.Label class={styles.Label}>{'Framework'}</Select.Label>
    <Select.Control class={styles.Control}>
      <Select.Trigger class={styles.Trigger}>
        <Select.ValueText class={styles.ValueText} placeholder="Select" />
        <Select.Indicator class={styles.Indicator}>
          <ChevronsUpDown />
        </Select.Indicator>
      </Select.Trigger>
      <Select.ClearTrigger class={styles.ClearTrigger}>
        <X />
      </Select.ClearTrigger>
    </Select.Control>
    <Portal>
      <Select.Positioner>
        <Select.Content class={styles.Content}>
          <Select.ItemGroup class={styles.ItemGroup}>
            <Select.ItemGroupLabel class={styles.ItemGroupLabel}>
              {'Frameworks'}
            </Select.ItemGroupLabel>
            for (const item of @collection.items; key item.value) {
              <Select.Item class={styles.Item} {item}>
                <Select.ItemText class={styles.ItemText}>{item.label}</Select.ItemText>
                <Select.ItemIndicator class={styles.ItemIndicator}>{'✓'}</Select.ItemIndicator>
              </Select.Item>
            }
          </Select.ItemGroup>
        </Select.Content>
      </Select.Positioner>
    </Portal>
    <Select.HiddenSelect />
  </Select.Root>
}

```

### Select All

Use `selectAll()` from the select context to select all items at once.

**Example: select-all**

```ripple
import { Portal } from 'ark-ripple/portal';
import { Select, createListCollection, useSelectContext } from 'ark-ripple/select';
import { ChevronsUpDown } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/select.module.css';

component SelectAllButton() {
  const select = useSelectContext();
  <Select.Context>
    component children({ context }) {
      <button
        class={button.Root}
        style="width: 100%; margin-bottom: 0.25rem"
        type="button"
        onClick={() => {
          @context.selectAll();
          context.setOpen(false);
        }}
      >
        {'Select All'}
      </button>
    }
  </Select.Context>
}

export component SelectAll() {
  const collection = createListCollection({ items: ['React', 'Solid', 'Vue', 'Svelte'] });

  <Select.Root class={styles.Root} {collection}>
    <Select.Label class={styles.Label}>{'Framework'}</Select.Label>
    <Select.Control class={styles.Control}>
      <Select.Trigger class={styles.Trigger}>
        <Select.ValueText class={styles.ValueText} placeholder="Select a Framework" />
        <Select.Indicator class={styles.Indicator}>
          <ChevronsUpDown />
        </Select.Indicator>
      </Select.Trigger>
      <Select.ClearTrigger class={styles.ClearTrigger}>{'Clear'}</Select.ClearTrigger>
    </Select.Control>
    <Portal>
      <Select.Positioner>
        <Select.Content class={styles.Content}>
          <SelectAllButton />
          for (const item of collection.items; key item) {
            <Select.Item class={styles.Item} {item}>
              <Select.ItemText class={styles.ItemText}>{item}</Select.ItemText>
              <Select.ItemIndicator class={styles.ItemIndicator}>{'✓'}</Select.ItemIndicator>
            </Select.Item>
          }
        </Select.Content>
      </Select.Positioner>
    </Portal>
    <Select.HiddenSelect />
  </Select.Root>
}

```

### Overflow

For selects with many items, use `positioning.fitViewport` to ensure the dropdown fits within the viewport. Combine with
a max-height on the content to enable scrolling.

**Example: overflow**

```ripple
import { Portal } from 'ark-ripple/portal';
import { Select, createListCollection } from 'ark-ripple/select';
import { ChevronsUpDown } from 'lucide-ripple';
import styles from 'styles/select.module.css';

const collection = createListCollection(
  {
    items: [
      'Name 1',
      'Name 2',
      'Name 3',
      'Name 4',
      'Name 5',
      'Name 6',
      'Name 7',
      'Name 8',
      'Name 9',
      'Name 10',
      'Name 11',
      'Name 12',
      'Name 13',
      'Name 14',
    ],
  },
);

export component Overflow() {
  <Select.Root
    class={styles.Root}
    {collection}
    positioning={{ fitViewport: true, placement: 'bottom-start', sameWidth: true }}
  >
    <Select.Label class={styles.Label}>{'Framework'}</Select.Label>
    <Select.Control class={styles.Control}>
      <Select.Trigger class={styles.Trigger}>
        <Select.ValueText class={styles.ValueText} placeholder="Select a Framework" />
        <Select.Indicator class={styles.Indicator}>
          <ChevronsUpDown />
        </Select.Indicator>
      </Select.Trigger>
      <Select.ClearTrigger class={styles.ClearTrigger}>{'Clear'}</Select.ClearTrigger>
    </Select.Control>
    <Portal>
      <Select.Positioner>
        <Select.Content class={styles.Content} style="max-height: 200px">
          <Select.ItemGroup class={styles.ItemGroup}>
            <Select.ItemGroupLabel class={styles.ItemGroupLabel}>{'Names'}</Select.ItemGroupLabel>
            for (const item of collection.items; key item) {
              <Select.Item class={styles.Item} {item}>
                <Select.ItemText class={styles.ItemText}>{item}</Select.ItemText>
                <Select.ItemIndicator class={styles.ItemIndicator}>{'✓'}</Select.ItemIndicator>
              </Select.Item>
            }
          </Select.ItemGroup>
        </Select.Content>
      </Select.Positioner>
    </Portal>
    <Select.HiddenSelect />
  </Select.Root>
}

```

## Guides

### Nested Usage

When using the Select component within a `Popover` or `Dialog`, avoid rendering its content within a `Portal` or
`Teleport`.

This ensures the Select's content stays within the Popover/Dialog's DOM hierarchy rather than being portalled to the
document body, maintaining proper interaction and accessibility behavior.

### Hidden Select

The `Select.HiddenSelect` component renders a native HTML `<select>` element that's visually hidden but remains in the
DOM. This component is essential for:

- **Form submission**: Native form submission and serialization work seamlessly since the actual `<select>` element
  exists in the DOM
- **Browser auto-fill**: Browsers can properly auto-fill the select based on previously submitted form data
- **Progressive enhancement**: Forms remain functional even if JavaScript fails to load

```tsx
<Select.Root>
  <Select.HiddenSelect />
  {/* Other Select components */}
</Select.Root>
```

The hidden select automatically syncs with the Select component's value, ensuring form data is always up-to-date.

### Empty State

You can create an empty state component that displays when there are no items in the collection. Use the
`useSelectContext` hook to check the collection size:

```tsx
component SelectEmpty(props) {
  const select = useSelectContext()
  if (@select.collection.size === 0) {
    <div {...props} role="presentation" />
  }
}
```

Then use it within your Select content:

```tsx
<Select.Content>
  <SelectEmpty>{"No items to display"}</SelectEmpty>
  {/* Your items */}
</Select.Content>
```

### Available Size

The following css variables are exposed to the `Select.Positioner` which you can use to style the `Select.Content`

```css
/* width of the select trigger */
--reference-width: <pixel-value>;
/* width of the available viewport */
--available-width: <pixel-value>;
/* height of the available viewport */
--available-height: <pixel-value>;
```

For example, if you want to make sure the maximum height doesn't exceed the available height, you can use the following:

```css
[data-scope='select'][data-part='content'] {
  max-height: calc(var(--available-height) - 100px);
}
```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `collection` | `ListCollection<T>` | Yes | The collection of items |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `autoComplete` | `string` | No | The autocomplete attribute for the hidden select. Enables browser autofill (e.g. "address-level1" for state). |
| `closeOnSelect` | `boolean` | No | Whether the select should close after an item is selected |
| `composite` | `boolean` | No | Whether the select is a composed with other composite widgets like tabs or combobox |
| `defaultHighlightedValue` | `string` | No | The initial value of the highlighted item when opened.
Use when you don't need to control the highlighted value of the select. |
| `defaultOpen` | `boolean` | No | Whether the select's open state is controlled by the user |
| `defaultValue` | `string[]` | No | The initial default value of the select when rendered.
Use when you don't need to control the value of the select. |
| `deselectable` | `boolean` | No | Whether the value can be cleared by clicking the selected item.

**Note:** this is only applicable for single selection |
| `disabled` | `boolean` | No | Whether the select is disabled |
| `form` | `string` | No | The associate form of the underlying select. |
| `highlightedValue` | `string` | No | The controlled key of the highlighted item |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{
  root: string
  content: string
  control: string
  trigger: string
  clearTrigger: string
  label: string
  hiddenSelect: string
  positioner: string
  item: (id: string | number) => string
  itemGroup: (id: string | number) => string
  itemGroupLabel: (id: string | number) => string
}>` | No | The ids of the elements in the select. Useful for composition. |
| `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame |
| `invalid` | `boolean` | No | Whether the select is invalid |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `loopFocus` | `boolean` | No | Whether to loop the keyboard navigation through the options |
| `multiple` | `boolean` | No | Whether to allow multiple selection |
| `name` | `string` | No | The `name` attribute of the underlying select. |
| `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state |
| `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component |
| `onHighlightChange` | `(details: HighlightChangeDetails<T>) => void` | No | The callback fired when the highlighted item changes. |
| `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component |
| `onOpenChange` | `(details: OpenChangeDetails) => void` | No | Function called when the popup is opened |
| `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component |
| `onSelect` | `(details: SelectionDetails) => void` | No | Function called when an item is selected |
| `onValueChange` | `(details: ValueChangeDetails<T>) => void` | No | The callback fired when the selected item changes. |
| `open` | `boolean` | No | Whether the select menu is open |
| `positioning` | `PositioningOptions` | No | The positioning options of the menu. |
| `present` | `boolean` | No | Whether the node is present (controlled by the user) |
| `readOnly` | `boolean` | No | Whether the select is read-only |
| `required` | `boolean` | No | Whether the select is required |
| `scrollToIndexFn` | `(details: ScrollToIndexDetails) => void` | No | Function to scroll to a specific index |
| `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |
| `value` | `string[]` | No | The controlled keys of the selected items |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | select |
| `[data-part]` | root |
| `[data-invalid]` | Present when invalid |
| `[data-readonly]` | Present when read-only |


**ClearTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ClearTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | select |
| `[data-part]` | clear-trigger |
| `[data-invalid]` | Present when invalid |


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | select |
| `[data-part]` | content |
| `[data-state]` | "open" | "closed" |
| `[data-nested]` | listbox |
| `[data-has-nested]` | listbox |
| `[data-placement]` | The placement of the content |
| `[data-activedescendant]` | The id the active descendant of the content |


**Content CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--layer-index` | The index of the dismissable in the layer stack |
| `--nested-layer-count` | The number of nested selects |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | select |
| `[data-part]` | control |
| `[data-state]` | "open" | "closed" |
| `[data-focus]` | Present when focused |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]` | Present when invalid |


**HiddenSelect Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Indicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Indicator Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | select |
| `[data-part]` | indicator |
| `[data-state]` | "open" | "closed" |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]` | Present when invalid |
| `[data-readonly]` | Present when read-only |


**ItemGroupLabel Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemGroup Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemGroup Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | select |
| `[data-part]` | item-group |
| `[data-disabled]` | Present when disabled |


**ItemIndicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemIndicator Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | select |
| `[data-part]` | item-indicator |
| `[data-state]` | "checked" | "unchecked" |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `item` | `any` | No | The item to render |
| `persistFocus` | `boolean` | No | Whether hovering outside should clear the highlighted state |


**Item Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | select |
| `[data-part]` | item |
| `[data-value]` | The value of the item |
| `[data-state]` | "checked" | "unchecked" |
| `[data-highlighted]` | Present when highlighted |
| `[data-disabled]` | Present when disabled |


**ItemText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemText Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | select |
| `[data-part]` | item-text |
| `[data-state]` | "checked" | "unchecked" |
| `[data-disabled]` | Present when disabled |
| `[data-highlighted]` | Present when highlighted |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | select |
| `[data-part]` | label |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]` | Present when invalid |
| `[data-readonly]` | Present when read-only |
| `[data-required]` | Present when required |


**List Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Positioner Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Positioner CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--reference-width` | The width of the reference element |
| `--reference-height` | The height of the root |
| `--available-width` | The available width in viewport |
| `--available-height` | The available height in viewport |
| `--x` | The x position for transform |
| `--y` | The y position for transform |
| `--z-index` | The z-index value |
| `--transform-origin` | The transform origin for animations |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseSelectReturn<T>` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state |
| `present` | `boolean` | No | Whether the node is present (controlled by the user) |
| `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


**Trigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | select |
| `[data-part]` | trigger |
| `[data-state]` | "open" | "closed" |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]` | Present when invalid |
| `[data-readonly]` | Present when read-only |
| `[data-placement]` | The placement of the trigger |
| `[data-placeholder-shown]` | Present when placeholder is shown |


**ValueText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `placeholder` | `string` | No | Text to display when no value is selected. |


**ValueText Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | select |
| `[data-part]` | value-text |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]` | Present when invalid |
| `[data-focus]` | Present when focused |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `focused` | `boolean` | Whether the select is focused |
| `open` | `boolean` | Whether the select is open |
| `empty` | `boolean` | Whether the select value is empty |
| `highlightedValue` | `string` | The value of the highlighted item |
| `highlightedItem` | `V` | The highlighted item |
| `setHighlightValue` | `(value: string) => void` | Function to highlight a value |
| `clearHighlightValue` | `VoidFunction` | Function to clear the highlighted value |
| `selectedItems` | `V[]` | The selected items |
| `hasSelectedItems` | `boolean` | Whether there's a selected option |
| `value` | `string[]` | The selected item keys |
| `valueAsString` | `string` | The string representation of the selected items |
| `selectValue` | `(value: string) => void` | Function to select a value |
| `selectAll` | `VoidFunction` | Function to select all values |
| `setValue` | `(value: string[]) => void` | Function to set the value of the select |
| `clearValue` | `(value?: string) => void` | Function to clear the value of the select.
If a value is provided, it will only clear that value, otherwise, it will clear all values. |
| `focus` | `VoidFunction` | Function to focus on the select input |
| `getItemState` | `(props: ItemProps<any>) => ItemState` | Returns the state of a select item |
| `setOpen` | `(open: boolean) => void` | Function to open or close the select |
| `collection` | `ListCollection<V>` | Function to toggle the select |
| `reposition` | `(options?: Partial<PositioningOptions>) => void` | Function to set the positioning options of the select |
| `multiple` | `boolean` | Whether the select allows multiple selections |
| `disabled` | `boolean` | Whether the select is disabled |


## Accessibility

Complies with the [Listbox WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/).

### Keyboard Support

**`Space`**
Description: <span>When focus is on trigger, opens the select and focuses the first selected item.<br />When focus is on the content, selects the highlighted item.</span>

**`Enter`**
Description: <span>When focus is on trigger, opens the select and focuses the first selected item.<br />When focus is on content, selects the focused item.</span>

**`ArrowDown`**
Description: <span>When focus is on trigger, opens the select.<br />When focus is on content, moves focus to the next item.</span>

**`ArrowUp`**
Description: <span>When focus is on trigger, opens the select.<br />When focus is on content, moves focus to the previous item.</span>

**`Esc`**
Description: <span>Closes the select and moves focus to trigger.</span>

**`A-Z + a-z`**
Description: <span>When focus is on trigger, selects the item whose label starts with the typed character.<br />When focus is on the listbox, moves focus to the next item with a label that starts with the typed character.</span>


# Signature Pad 



## Anatomy



```tsx
<SignaturePad.Root>
  <SignaturePad.Label />
  <SignaturePad.Control>
    <SignaturePad.Segment />
    <SignaturePad.ClearTrigger />
    <SignaturePad.Guide />
  </SignaturePad.Control>
</SignaturePad.Root>
```

## Examples

**Example: basic**

```ripple
import { SignaturePad } from 'ark-ripple/signature-pad';
import styles from 'styles/signature-pad.module.css';

export component Basic() {
  <SignaturePad.Root class={styles.Root}>
    <SignaturePad.Label class={styles.Label}>{'Sign below'}</SignaturePad.Label>
    <SignaturePad.Control class={styles.Control}>
      <SignaturePad.Segment class={styles.Segment} />
      <SignaturePad.ClearTrigger class={styles.ClearTrigger}>{'↺'}</SignaturePad.ClearTrigger>
      <SignaturePad.Guide class={styles.Guide} />
    </SignaturePad.Control>
  </SignaturePad.Root>
}

```

### 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.

**Example: image-preview**

```ripple
import { SignaturePad } from 'ark-ripple/signature-pad';
import { track } from 'ripple';
import styles from 'styles/signature-pad.module.css';

export component ImagePreview() {
  let imageUrl = track('');

  <div class="stack">
    <SignaturePad.Root
      class={styles.Root}
      onDrawEnd={(details) => {
        details.getDataUrl('image/png').then((url) => {
          @imageUrl = url;
        });
      }}
    >
      <SignaturePad.Label class={styles.Label}>{'Sign below'}</SignaturePad.Label>
      <SignaturePad.Control class={styles.Control}>
        <SignaturePad.Segment class={styles.Segment} />
        <SignaturePad.ClearTrigger class={styles.ClearTrigger}>{'↺'}</SignaturePad.ClearTrigger>
        <SignaturePad.Guide class={styles.Guide} />
      </SignaturePad.Control>
    </SignaturePad.Root>
    <div class="stack">
      <span>{'Image Preview'}</span>
      if (@imageUrl) {
        <img src={@imageUrl} alt="Signature" class={styles.Image} />
      }
    </div>
  </div>
}

```

### Field

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.

**Example: with-field**

```ripple
import { Field } from 'ark-ripple/field';
import { SignaturePad } from 'ark-ripple/signature-pad';
import field from 'styles/field.module.css';
import styles from 'styles/signature-pad.module.css';

export component WithField() {
  <Field.Root class={field.Root}>
    <SignaturePad.Root class={styles.Root}>
      <SignaturePad.Label class={styles.Label}>{'Label'}</SignaturePad.Label>
      <SignaturePad.Control class={styles.Control}>
        <SignaturePad.Segment class={styles.Segment} />
        <SignaturePad.ClearTrigger class={styles.ClearTrigger}>{'↺'}</SignaturePad.ClearTrigger>
        <SignaturePad.Guide class={styles.Guide} />
      </SignaturePad.Control>
    </SignaturePad.Root>
    <Field.HelperText class={field.HelperText}>{'Additional Info'}</Field.HelperText>
    <Field.ErrorText class={field.ErrorText}>{'Error Info'}</Field.ErrorText>
  </Field.Root>
}

```

### Root Provider

An alternative way to control the signature pad is to use the `RootProvider` component and the `useSignaturePad` hook.
This way you can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { SignaturePad, useSignaturePad } from 'ark-ripple/signature-pad';
import styles from 'styles/signature-pad.module.css';

export component RootProvider() {
  const signaturePad = useSignaturePad();

  <div class="stack">
    <output>
      {'no of paths: '}
      {@signaturePad.paths.length}
    </output>
    <SignaturePad.RootProvider class={styles.Root} value={signaturePad}>
      <SignaturePad.Label class={styles.Label}>{'Sign below'}</SignaturePad.Label>
      <SignaturePad.Control class={styles.Control}>
        <SignaturePad.Segment class={styles.Segment} />
        <SignaturePad.ClearTrigger class={styles.ClearTrigger}>{'↺'}</SignaturePad.ClearTrigger>
        <SignaturePad.Guide class={styles.Guide} />
      </SignaturePad.Control>
    </SignaturePad.RootProvider>
  </div>
}

```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `defaultPaths` | `string[]` | No | The default paths of the signature pad.
Use when you don't need to control the paths of the signature pad. |
| `disabled` | `boolean` | No | Whether the signature pad is disabled. |
| `drawing` | `DrawingOptions` | No | The drawing options. |
| `ids` | `Partial<{ root: string; control: string; hiddenInput: string; label: string }>` | No | The ids of the signature pad elements. Useful for composition. |
| `name` | `string` | No | The name of the signature pad. Useful for form submission. |
| `onDraw` | `(details: DrawDetails) => void` | No | Callback when the signature pad is drawing. |
| `onDrawEnd` | `(details: DrawEndDetails) => void` | No | Callback when the signature pad is done drawing. |
| `paths` | `string[]` | No | The controlled paths of the signature pad. |
| `readOnly` | `boolean` | No | Whether the signature pad is read-only. |
| `required` | `boolean` | No | Whether the signature pad is required. |
| `translations` | `IntlTranslations` | No | The translations of the signature pad. Useful for internationalization. |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | signature-pad |
| `[data-part]` | root |
| `[data-disabled]` | Present when disabled |


**ClearTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | signature-pad |
| `[data-part]` | control |
| `[data-disabled]` | Present when disabled |


**Guide Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Guide Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | signature-pad |
| `[data-part]` | guide |
| `[data-disabled]` | Present when disabled |


**HiddenInput Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `string` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | signature-pad |
| `[data-part]` | label |
| `[data-disabled]` | Present when disabled |
| `[data-required]` | Present when required |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseSignaturePadReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Segment Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `empty` | `boolean` | Whether the signature pad is empty. |
| `drawing` | `boolean` | Whether the user is currently drawing. |
| `currentPath` | `string` | The current path being drawn. |
| `paths` | `string[]` | The paths of the signature pad. |
| `getDataUrl` | `(type: DataUrlType, quality?: number) => Promise<string>` | Returns the data URL of the signature pad. |
| `clear` | `VoidFunction` | Clears the signature pad. |



# Slider 



## Anatomy



```tsx
<Slider.Root>
  <Slider.Label />
  <Slider.ValueText />
  <Slider.Control>
    <Slider.Track>
      <Slider.Range />
    </Slider.Track>
    <Slider.Thumb>
      <Slider.HiddenInput />
    </Slider.Thumb>
  </Slider.Control>
  <Slider.MarkerGroup>
    <Slider.Marker />
  </Slider.MarkerGroup>
</Slider.Root>
```

## Examples

**Example: basic**

```ripple
import { Slider } from 'ark-ripple/slider';
import styles from 'styles/slider.module.css';

export component Basic() {
  <Slider.Root class={styles.Root} defaultValue={[40]}>
    <div style={{ display: 'flex', justifyContent: 'space-between' }}>
      <Slider.Label class={styles.Label}>{'Label'}</Slider.Label>
      <Slider.ValueText class={styles.ValueText} />
    </div>
    <Slider.Control class={styles.Control}>
      <Slider.Track class={styles.Track}>
        <Slider.Range class={styles.Range} />
      </Slider.Track>
      <Slider.Thumb index={0} class={styles.Thumb}>
        <Slider.HiddenInput />
      </Slider.Thumb>
    </Slider.Control>
  </Slider.Root>
}

```

### Range

You can add multiple thumbs to the slider by adding multiple `Slider.Thumb`

**Example: range**

```ripple
import { Slider } from 'ark-ripple/slider';
import styles from 'styles/slider.module.css';

export component Range() {
  <Slider.Root defaultValue={[30, 60]} class={styles.Root}>
    <Slider.Label class={styles.Label}>{'Label'}</Slider.Label>
    <Slider.Control class={styles.Control}>
      <Slider.Track class={styles.Track}>
        <Slider.Range class={styles.Range} />
      </Slider.Track>
      <Slider.Thumb index={0} class={styles.Thumb}>
        <Slider.HiddenInput />
      </Slider.Thumb>
      <Slider.Thumb index={1} class={styles.Thumb}>
        <Slider.HiddenInput />
      </Slider.Thumb>
    </Slider.Control>
  </Slider.Root>
}

```

### 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.

**Example: with-marks**

```ripple
import { Slider } from 'ark-ripple/slider';
import styles from 'styles/slider.module.css';

const marks = [0, 25, 50, 75, 100];

export component WithMarks() {
  <Slider.Root class={styles.Root} defaultValue={[50]}>
    <div style={{ display: 'flex', justifyContent: 'space-between' }}>
      <Slider.Label class={styles.Label}>{'Label'}</Slider.Label>
      <Slider.ValueText class={styles.ValueText} />
    </div>
    <Slider.Control class={styles.Control}>
      <Slider.Track class={styles.Track}>
        <Slider.Range class={styles.Range} />
      </Slider.Track>
      <Slider.Thumb index={0} class={styles.Thumb}>
        <Slider.HiddenInput />
      </Slider.Thumb>
    </Slider.Control>
    <Slider.MarkerGroup class={styles.MarkerGroup}>
      for (const value of marks; key value) {
        <Slider.Marker {value} class={styles.Marker}>{value}</Slider.Marker>
      }
    </Slider.MarkerGroup>
  </Slider.Root>
}

```

### Min and Max

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:

**Example: min-max**

```ripple
import { Slider } from 'ark-ripple/slider';
import styles from 'styles/slider.module.css';

export component MinMax() {
  <Slider.Root min={-10} max={10} defaultValue={[5]} class={styles.Root}>
    <div style={{ display: 'flex', justifyContent: 'space-between' }}>
      <Slider.Label class={styles.Label}>{'Label'}</Slider.Label>
      <Slider.ValueText class={styles.ValueText} />
    </div>
    <Slider.Control class={styles.Control}>
      <Slider.Track class={styles.Track}>
        <Slider.Range class={styles.Range} />
      </Slider.Track>
      <Slider.Thumb index={0} class={styles.Thumb}>
        <Slider.HiddenInput />
      </Slider.Thumb>
    </Slider.Control>
  </Slider.Root>
}

```

### 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`:

**Example: step**

```ripple
import { Slider } from 'ark-ripple/slider';
import styles from 'styles/slider.module.css';

export component Step() {
  <Slider.Root step={0.01} min={5} max={10} defaultValue={[7.5]} class={styles.Root}>
    <div style={{ display: 'flex', justifyContent: 'space-between' }}>
      <Slider.Label class={styles.Label}>{'Label'}</Slider.Label>
      <Slider.ValueText class={styles.ValueText} />
    </div>
    <Slider.Control class={styles.Control}>
      <Slider.Track class={styles.Track}>
        <Slider.Range class={styles.Range} />
      </Slider.Track>
      <Slider.Thumb index={0} class={styles.Thumb}>
        <Slider.HiddenInput />
      </Slider.Thumb>
    </Slider.Control>
  </Slider.Root>
}

```

### Change Events

When the slider value changes, the `onValueChange` and `onValueChangeEnd` callbacks are invoked. You can use this to set
up custom behaviors in your app.

**Example: on-event**

```ripple
import { Slider } from 'ark-ripple/slider';
import styles from 'styles/slider.module.css';

export component OnEvent() {
  <Slider.Root
    onValueChange={(details) => console.log('onValueChange', details.value)}
    onValueChangeEnd={(details) => console.log('onValueChangeEnd', details.value)}
    class={styles.Root}
  >
    <div style={{ display: 'flex', justifyContent: 'space-between' }}>
      <Slider.Label class={styles.Label}>{'Label'}</Slider.Label>
      <Slider.ValueText class={styles.ValueText} />
    </div>
    <Slider.Control class={styles.Control}>
      <Slider.Track class={styles.Track}>
        <Slider.Range class={styles.Range} />
      </Slider.Track>
      <Slider.Thumb index={0} class={styles.Thumb}>
        <Slider.HiddenInput />
      </Slider.Thumb>
    </Slider.Control>
  </Slider.Root>
}

```

### 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

**Example: vertical**

```ripple
import { Slider } from 'ark-ripple/slider';
import styles from 'styles/slider.module.css';

export component Vertical() {
  <Slider.Root orientation="vertical" class={styles.Root}>
    <Slider.Label class={styles.Label}>{'Label'}</Slider.Label>
    <Slider.ValueText class={styles.ValueText} />
    <Slider.Control class={styles.Control}>
      <Slider.Track class={styles.Track}>
        <Slider.Range class={styles.Range} />
      </Slider.Track>
      <Slider.Thumb index={0} class={styles.Thumb}>
        <Slider.HiddenInput />
      </Slider.Thumb>
    </Slider.Control>
  </Slider.Root>
}

```

### 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`.

**Example: center-origin**

```ripple
import { Slider } from 'ark-ripple/slider';
import styles from 'styles/slider.module.css';

export component CenterOrigin() {
  <Slider.Root origin="center" class={styles.Root} defaultValue={[75]}>
    <div style={{ display: 'flex', justifyContent: 'space-between' }}>
      <Slider.Label class={styles.Label}>{'Label'}</Slider.Label>
      <Slider.ValueText class={styles.ValueText} />
    </div>
    <Slider.Control class={styles.Control}>
      <Slider.Track class={styles.Track}>
        <Slider.Range class={styles.Range} />
      </Slider.Track>
      <Slider.Thumb index={0} class={styles.Thumb}>
        <Slider.HiddenInput />
      </Slider.Thumb>
    </Slider.Control>
  </Slider.Root>
}

```

### Root Provider

An alternative way to control the slider is to use the `RootProvider` component and the `useSlider` hook. This way you
can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { Slider, useSlider } from 'ark-ripple/slider';
import styles from 'styles/slider.module.css';
import button from 'styles/button.module.css';

export component RootProvider() {
  const slider = useSlider();

  <button class={button.Root} onClick={() => @slider.focus()}>{'Focus'}</button>
  <Slider.RootProvider value={slider} class={styles.Root}>
    <Slider.Label class={styles.Label}>{'Label'}</Slider.Label>
    <Slider.ValueText class={styles.ValueText} />
    <Slider.Control class={styles.Control}>
      <Slider.Track class={styles.Track}>
        <Slider.Range class={styles.Range} />
      </Slider.Track>
      <Slider.Thumb index={0} class={styles.Thumb}>
        <Slider.HiddenInput />
      </Slider.Thumb>
    </Slider.Control>
  </Slider.RootProvider>
}

```

### Dragging Indicator

Use the `Slider.DraggingIndicator` component inside `Slider.Thumb` to show a visual indicator while the thumb is being
dragged.

**Example: dragging-indicator**

```ripple
import { Slider } from 'ark-ripple/slider';
import styles from 'styles/slider.module.css';

export component DraggingIndicator() {
  <Slider.Root class={styles.Root} defaultValue={[40]}>
    <Slider.Label class={styles.Label}>{'Label'}</Slider.Label>
    <Slider.Control class={styles.Control}>
      <Slider.Track class={styles.Track}>
        <Slider.Range class={styles.Range} />
      </Slider.Track>
      <Slider.Thumb index={0} class={styles.Thumb}>
        <Slider.DraggingIndicator class={styles.DraggingIndicator} />
        <Slider.HiddenInput />
      </Slider.Thumb>
    </Slider.Control>
  </Slider.Root>
}

```

### Thumb Overlap

Use the `minStepsBetweenThumbs` prop to prevent range slider thumbs from overlapping. This ensures a minimum gap between
thumbs, which is useful for price range filters and similar use cases.

**Example: thumb-overlap**

```ripple
import { Slider } from 'ark-ripple/slider';
import styles from 'styles/slider.module.css';

export component ThumbOverlap() {
  <Slider.Root minStepsBetweenThumbs={5} defaultValue={[25, 60]} class={styles.Root}>
    <div style={{ display: 'flex', justifyContent: 'space-between' }}>
      <Slider.Label class={styles.Label}>{'Label'}</Slider.Label>
      <Slider.ValueText class={styles.ValueText} />
    </div>
    <Slider.Control class={styles.Control}>
      <Slider.Track class={styles.Track}>
        <Slider.Range class={styles.Range} />
      </Slider.Track>
      <Slider.Thumb index={0} class={styles.Thumb}>
        <Slider.HiddenInput />
      </Slider.Thumb>
      <Slider.Thumb index={1} class={styles.Thumb}>
        <Slider.HiddenInput />
      </Slider.Thumb>
    </Slider.Control>
  </Slider.Root>
}

```

### Thumb Collision

Use the `thumbCollisionBehavior` prop to control how thumbs behave when they collide during pointer interactions.
Supported values are `push` (default), `swap`, and `none`.

**Example: thumb-collision**

```ripple
import { Slider } from 'ark-ripple/slider';
import styles from 'styles/slider.module.css';

export component ThumbCollision() {
  <Slider.Root thumbCollisionBehavior="push" defaultValue={[25, 60]} class={styles.Root}>
    <div style={{ display: 'flex', justifyContent: 'space-between' }}>
      <Slider.Label class={styles.Label}>{'Label'}</Slider.Label>
      <Slider.ValueText class={styles.ValueText} />
    </div>
    <Slider.Control class={styles.Control}>
      <Slider.Track class={styles.Track}>
        <Slider.Range class={styles.Range} />
      </Slider.Track>
      <Slider.Thumb index={0} class={styles.Thumb}>
        <Slider.HiddenInput />
      </Slider.Thumb>
      <Slider.Thumb index={1} class={styles.Thumb}>
        <Slider.HiddenInput />
      </Slider.Thumb>
    </Slider.Control>
  </Slider.Root>
}

```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `aria-label` | `string[]` | No | The aria-label of each slider thumb. Useful for providing an accessible name to the slider |
| `aria-labelledby` | `string[]` | No | The `id` of the elements that labels each slider thumb. Useful for providing an accessible name to the slider |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `defaultValue` | `number[]` | No | The initial value of the slider when rendered.
Use when you don't need to control the value of the slider. |
| `disabled` | `boolean` | No | Whether the slider is disabled |
| `form` | `string` | No | The associate form of the underlying input element. |
| `getAriaValueText` | `(details: ValueTextDetails) => string` | No | Function that returns a human readable value for the slider thumb |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{
  root: string
  thumb: (index: number) => string
  hiddenInput: (index: number) => string
  control: string
  track: string
  range: string
  label: string
  valueText: string
  marker: (index: number) => string
}>` | No | The ids of the elements in the slider. Useful for composition. |
| `invalid` | `boolean` | No | Whether the slider is invalid |
| `max` | `number` | No | The maximum value of the slider |
| `min` | `number` | No | The minimum value of the slider |
| `minStepsBetweenThumbs` | `number` | No | The minimum permitted steps between multiple thumbs.

`minStepsBetweenThumbs` * `step` should reflect the gap between the thumbs.

- `step: 1` and `minStepsBetweenThumbs: 10` => gap is `10`
- `step: 10` and `minStepsBetweenThumbs: 2` => gap is `20` |
| `name` | `string` | No | The name associated with each slider thumb (when used in a form) |
| `onFocusChange` | `(details: FocusChangeDetails) => void` | No | Function invoked when the slider's focused index changes |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | Function invoked when the value of the slider changes |
| `onValueChangeEnd` | `(details: ValueChangeDetails) => void` | No | Function invoked when the slider value change is done |
| `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the slider |
| `origin` | `'center' | 'start' | 'end'` | No | The origin of the slider range. The track is filled from the origin
to the thumb for single values.
- "start": Useful when the value represents an absolute value
- "center": Useful when the value represents an offset (relative)
- "end": Useful when the value represents an offset from the end |
| `readOnly` | `boolean` | No | Whether the slider is read-only |
| `step` | `number` | No | The step value of the slider |
| `thumbAlignment` | `'center' | 'contain'` | No | The alignment of the slider thumb relative to the track
- `center`: the thumb will extend beyond the bounds of the slider track.
- `contain`: the thumb will be contained within the bounds of the track. |
| `thumbCollisionBehavior` | `'none' | 'push' | 'swap'` | No | Controls how thumbs behave when they collide during pointer interactions.
- `none` (default): Thumbs cannot move past each other; excess movement is ignored.
- `push`: Thumbs push each other without restoring their previous positions when dragged back.
- `swap`: Thumbs swap places when dragged past each other. |
| `thumbSize` | `{ width: number; height: number }` | No | The slider thumbs dimensions |
| `value` | `number[]` | No | The controlled value of the slider |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | slider |
| `[data-part]` | root |
| `[data-disabled]` | Present when disabled |
| `[data-orientation]` | The orientation of the slider |
| `[data-dragging]` | Present when in the dragging state |
| `[data-invalid]` | Present when invalid |
| `[data-focus]` | Present when focused |


**Root CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--slider-thumb-width` | The thumb width of the slider |
| `--slider-thumb-height` | The thumb height of the slider |
| `--slider-thumb-transform` | The thumb transform of the slider |
| `--slider-range-start` | The range start of the slider |
| `--slider-range-end` | The range end of the slider |
| `--translate-x` | The horizontal translation value |
| `--translate-y` | The vertical translation value |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | slider |
| `[data-part]` | control |
| `[data-dragging]` | Present when in the dragging state |
| `[data-disabled]` | Present when disabled |
| `[data-orientation]` | The orientation of the control |
| `[data-invalid]` | Present when invalid |
| `[data-focus]` | Present when focused |


**DraggingIndicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**DraggingIndicator Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | slider |
| `[data-part]` | dragging-indicator |
| `[data-orientation]` | The orientation of the draggingindicator |
| `[data-state]` | "open" | "closed" |


**HiddenInput Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | slider |
| `[data-part]` | label |
| `[data-disabled]` | Present when disabled |
| `[data-orientation]` | The orientation of the label |
| `[data-invalid]` | Present when invalid |
| `[data-dragging]` | Present when in the dragging state |
| `[data-focus]` | Present when focused |


**MarkerGroup Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**MarkerGroup Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | slider |
| `[data-part]` | marker-group |
| `[data-orientation]` | The orientation of the markergroup |


**Marker Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `number` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Marker Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | slider |
| `[data-part]` | marker |
| `[data-orientation]` | The orientation of the marker |
| `[data-value]` | The value of the item |
| `[data-disabled]` | Present when disabled |
| `[data-state]` |  |


**Range Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Range Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | slider |
| `[data-part]` | range |
| `[data-dragging]` | Present when in the dragging state |
| `[data-focus]` | Present when focused |
| `[data-invalid]` | Present when invalid |
| `[data-disabled]` | Present when disabled |
| `[data-orientation]` | The orientation of the range |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseSliderReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Thumb Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `name` | `string` | No |  |


**Thumb Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | slider |
| `[data-part]` | thumb |
| `[data-index]` | The index of the item |
| `[data-name]` |  |
| `[data-disabled]` | Present when disabled |
| `[data-orientation]` | The orientation of the thumb |
| `[data-focus]` | Present when focused |
| `[data-dragging]` | Present when in the dragging state |


**Track Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Track Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | slider |
| `[data-part]` | track |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]` | Present when invalid |
| `[data-dragging]` | Present when in the dragging state |
| `[data-orientation]` | The orientation of the track |
| `[data-focus]` | Present when focused |


**ValueText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ValueText Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | slider |
| `[data-part]` | value-text |
| `[data-disabled]` | Present when disabled |
| `[data-orientation]` | The orientation of the valuetext |
| `[data-invalid]` | Present when invalid |
| `[data-focus]` | Present when focused |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `value` | `number[]` | The value of the slider. |
| `dragging` | `boolean` | Whether the slider is being dragged. |
| `focused` | `boolean` | Whether the slider is focused. |
| `setValue` | `(value: number[]) => void` | Function to set the value of the slider. |
| `getThumbValue` | `(index: number) => number` | Returns the value of the thumb at the given index. |
| `setThumbValue` | `(index: number, value: number) => void` | Sets the value of the thumb at the given index. |
| `getValuePercent` | `(value: number) => number` | Returns the percent of the thumb at the given index. |
| `getPercentValue` | `(percent: number) => number` | Returns the value of the thumb at the given percent. |
| `getThumbPercent` | `(index: number) => number` | Returns the percent of the thumb at the given index. |
| `setThumbPercent` | `(index: number, percent: number) => void` | Sets the percent of the thumb at the given index. |
| `getThumbMin` | `(index: number) => number` | Returns the min value of the thumb at the given index. |
| `getThumbMax` | `(index: number) => number` | Returns the max value of the thumb at the given index. |
| `increment` | `(index: number) => void` | Function to increment the value of the slider at the given index. |
| `decrement` | `(index: number) => void` | Function to decrement the value of the slider at the given index. |
| `focus` | `VoidFunction` | Function to focus the slider. This focuses the first thumb. |


## Accessibility

Complies with the [Slider WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider/).

### Keyboard Support

**`ArrowRight`**
Description: <span>Increments the slider based on defined step</span>

**`ArrowLeft`**
Description: <span>Decrements the slider based on defined step</span>

**`ArrowUp`**
Description: <span>Increases the value by the step amount.</span>

**`ArrowDown`**
Description: <span>Decreases the value by the step amount.</span>

**`PageUp`**
Description: <span>Increases the value by a larger step</span>

**`PageDown`**
Description: <span>Decreases the value by a larger step</span>

**`Shift + ArrowUp`**
Description: <span>Increases the value by a larger step</span>

**`Shift + ArrowDown`**
Description: <span>Decreases the value by a larger step</span>

**`Home`**
Description: Sets the value to its minimum.

**`End`**
Description: Sets the value to its maximum.


# Splitter 



## Anatomy



```tsx
<Splitter.Root>
  <Splitter.Panel />
  <Splitter.ResizeTrigger>
    <Splitter.ResizeTriggerIndicator />
  </Splitter.ResizeTrigger>
  <Splitter.Panel />
</Splitter.Root>
```

## Examples

**Example: basic**

```ripple
import { Splitter } from 'ark-ripple/splitter';
import styles from 'styles/splitter.module.css';

export component Basic() {
  <Splitter.Root class={styles.Root} panels={[{ id: 'a' }, { id: 'b' }]}>
    <Splitter.Panel class={styles.Panel} id="a">{'A'}</Splitter.Panel>
    <Splitter.ResizeTrigger class={styles.ResizeTrigger} id="a:b" aria-label="Resize">
      <Splitter.ResizeTriggerIndicator class={styles.ResizeTriggerIndicator} />
    </Splitter.ResizeTrigger>
    <Splitter.Panel class={styles.Panel} id="b">{'B'}</Splitter.Panel>
  </Splitter.Root>
}

```

### Context

Access the splitter's API with `Splitter.Context` or the `useSplitterContext` hook. This lets you resize panels
programmatically:

**Example: context**

```ripple
import { Splitter } from 'ark-ripple/splitter';
import button from 'styles/button.module.css';
import styles from 'styles/splitter.module.css';

export component Context() {
  <Splitter.Root class={styles.Root} panels={[{ id: 'a' }, { id: 'b' }]}>
    <Splitter.Context>
      component children({ context }) {
        <Splitter.Panel class={styles.Panel} id="a">
          <button class={button.Root} type="button" onClick={() => @context.resizePanel('a', 10)}>
            {'Set to 10%'}
          </button>
        </Splitter.Panel>
        <Splitter.ResizeTrigger class={styles.ResizeTrigger} id="a:b" aria-label="Resize">
          <Splitter.ResizeTriggerIndicator class={styles.ResizeTriggerIndicator} />
        </Splitter.ResizeTrigger>
        <Splitter.Panel class={styles.Panel} id="b">
          <button class={button.Root} type="button" onClick={() => @context.resizePanel('b', 10)}>
            {'Set to 10%'}
          </button>
        </Splitter.Panel>
      }
    </Splitter.Context>
  </Splitter.Root>
}

```

### Vertical

By default, the Splitter component is horizontal. If you need a vertical splitter, use the `orientation` prop:

**Example: vertical**

```ripple
import { Splitter } from 'ark-ripple/splitter';
import styles from 'styles/splitter.module.css';

export component Vertical() {
  <Splitter.Root class={styles.Root} orientation="vertical" panels={[{ id: 'a' }, { id: 'b' }]}>
    <Splitter.Panel class={styles.Panel} id="a">{'A'}</Splitter.Panel>
    <Splitter.ResizeTrigger class={styles.ResizeTrigger} id="a:b" aria-label="Resize">
      <Splitter.ResizeTriggerIndicator class={styles.ResizeTriggerIndicator} />
    </Splitter.ResizeTrigger>
    <Splitter.Panel class={styles.Panel} id="b">{'B'}</Splitter.Panel>
  </Splitter.Root>
}

```

### 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.

**Example: collapsible**

```ripple
import { Splitter } from 'ark-ripple/splitter';
import styles from 'styles/splitter.module.css';

export component Collapsible() {
  <Splitter.Root
    class={styles.Root}
    defaultSize={[15, 20]}
    panels={[
      { id: 'a', collapsible: true, collapsedSize: 5, minSize: 10, maxSize: 20 },
      { id: 'b', minSize: 50 },
    ]}
  >
    <Splitter.Panel class={styles.Panel} id="a">{'A'}</Splitter.Panel>
    <Splitter.ResizeTrigger class={styles.ResizeTrigger} id="a:b" aria-label="Resize">
      <Splitter.ResizeTriggerIndicator class={styles.ResizeTriggerIndicator} />
    </Splitter.ResizeTrigger>
    <Splitter.Panel class={styles.Panel} id="b">{'B'}</Splitter.Panel>
  </Splitter.Root>
}

```

### Multiple Panels

Here's an example of how to use the `Splitter` component with multiple panels.

**Example: multiple-panels**

```ripple
import { Splitter } from 'ark-ripple/splitter';
import styles from 'styles/splitter.module.css';

export component MultiplePanels() {
  <Splitter.Root
    class={styles.Root}
    panels={[
      { id: 'a', minSize: 20 },
      { id: 'b', minSize: 40 },
      { id: 'c', minSize: 20 },
    ]}
    defaultSize={[20, 60, 20]}
  >
    <Splitter.Panel class={styles.Panel} id="a">{'A'}</Splitter.Panel>
    <Splitter.ResizeTrigger class={styles.ResizeTrigger} id="a:b" aria-label="Resize">
      <Splitter.ResizeTriggerIndicator class={styles.ResizeTriggerIndicator} />
    </Splitter.ResizeTrigger>
    <Splitter.Panel class={styles.Panel} id="b">{'B'}</Splitter.Panel>
    <Splitter.ResizeTrigger class={styles.ResizeTrigger} id="b:c" aria-label="Resize">
      <Splitter.ResizeTriggerIndicator class={styles.ResizeTriggerIndicator} />
    </Splitter.ResizeTrigger>
    <Splitter.Panel class={styles.Panel} id="c">{'C'}</Splitter.Panel>
  </Splitter.Root>
}

```

### Root Provider

An alternative way to control the splitter is to use the `RootProvider` component and the `useSplitter` hook. This way
you can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { Splitter, useSplitter } from 'ark-ripple/splitter';
import styles from 'styles/splitter.module.css';

export component RootProvider() {
  const splitter = useSplitter(
    {
      defaultSize: [50, 50],
      panels: [{ id: 'a' }, { id: 'b' }],
    },
  );

  <div class="stack">
    <output>
      {'current size: '}
      {JSON.stringify(@splitter.getSizes())}
    </output>

    <Splitter.RootProvider class={styles.Root} value={splitter}>
      <Splitter.Panel class={styles.Panel} id="a">{'A'}</Splitter.Panel>
      <Splitter.ResizeTrigger class={styles.ResizeTrigger} id="a:b" aria-label="Resize">
        <Splitter.ResizeTriggerIndicator class={styles.ResizeTriggerIndicator} />
      </Splitter.ResizeTrigger>
      <Splitter.Panel class={styles.Panel} id="b">{'B'}</Splitter.Panel>
    </Splitter.RootProvider>
  </div>
}

```

### Resize Indicator

Use the `Splitter.ResizeTriggerIndicator` component to show a visual indicator on the resize handle.

**Example: resize-indicator**

```ripple
import { Splitter } from 'ark-ripple/splitter';
import styles from 'styles/splitter.module.css';

export component ResizeIndicator() {
  <Splitter.Root class={styles.Root} panels={[{ id: 'a' }, { id: 'b' }]}>
    <Splitter.Panel class={styles.Panel} id="a">{'A'}</Splitter.Panel>
    <Splitter.ResizeTrigger class={styles.ResizeTrigger} id="a:b" aria-label="Resize">
      <Splitter.ResizeTriggerIndicator class={styles.ResizeTriggerIndicator} />
    </Splitter.ResizeTrigger>
    <Splitter.Panel class={styles.Panel} id="b">{'B'}</Splitter.Panel>
  </Splitter.Root>
}

```

### Dynamic Collapsible

Use the `collapsePanel()` and `expandPanel()` methods to programmatically control panel collapse based on viewport size.
This is useful for responsive sidebar layouts that collapse on smaller screens.

**Example: dynamic-collapsible**

```ripple
import { Splitter, useSplitter } from 'ark-ripple/splitter';
import { track, effect } from 'ripple';
import styles from 'styles/splitter.module.css';

export component DynamicCollapsible() {
  let rootSize = track<number | null>(null);
  let rootEl: HTMLDivElement | null = null;

  effect(() => {
    const handleResize = () => {
      @rootSize = rootEl?.offsetWidth ?? null;
    };
    handleResize();
    window.addEventListener('resize', handleResize);
    return () => window.removeEventListener('resize', handleResize);
  });

  const isBelowMd = track(() => @rootSize != null && @rootSize < 600);

  const splitterProps = track(
    () => ({
      panels: [
        { id: 'a', collapsible: @isBelowMd, collapsedSize: 5, minSize: 20, maxSize: 40 },
        { id: 'b' },
      ] as const,
      defaultSize: [15, 85],
    }),
  );

  const splitter = useSplitter(splitterProps);

  effect(() => {
    if (@isBelowMd) @splitter.collapsePanel('a');
    else @splitter.expandPanel('a');
  });

  <Splitter.RootProvider
    class={styles.Root}
    value={splitter}
    {ref (el: HTMLDivElement) => {
      rootEl = el;
    }}
  >
    <Splitter.Panel class={styles.Panel} id="a">{'A'}</Splitter.Panel>
    <Splitter.ResizeTrigger class={styles.ResizeTrigger} id="a:b" aria-label="Resize panels">
      <Splitter.ResizeTriggerIndicator class={styles.ResizeTriggerIndicator} />
    </Splitter.ResizeTrigger>
    <Splitter.Panel class={styles.Panel} id="b">{'B'}</Splitter.Panel>
  </Splitter.RootProvider>
}

```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `panels` | `PanelData[]` | Yes | The size constraints of the panels. |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `defaultSize` | `number[]` | No | The initial size of the panels when rendered.
Use when you don't need to control the size of the panels. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{
  root: string
  resizeTrigger: (id: string) => string
  label: (id: string) => string
  panel: (id: string | number) => string
}>` | No | The ids of the elements in the splitter. Useful for composition. |
| `keyboardResizeBy` | `number` | No | The number of pixels to resize the panel by when the keyboard is used. |
| `nonce` | `string` | No | The nonce for the injected splitter cursor stylesheet. |
| `onCollapse` | `(details: ExpandCollapseDetails) => void` | No | Function called when a panel is collapsed. |
| `onExpand` | `(details: ExpandCollapseDetails) => void` | No | Function called when a panel is expanded. |
| `onResize` | `(details: ResizeDetails) => void` | No | Function called when the splitter is resized. |
| `onResizeEnd` | `(details: ResizeEndDetails) => void` | No | Function called when the splitter resize ends. |
| `onResizeStart` | `() => void` | No | Function called when the splitter resize starts. |
| `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the splitter. Can be `horizontal` or `vertical` |
| `size` | `number[]` | No | The controlled size data of the panels |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | splitter |
| `[data-part]` | root |
| `[data-orientation]` | The orientation of the splitter |
| `[data-dragging]` | Present when in the dragging state |


**Panel Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `id` | `string` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Panel Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | splitter |
| `[data-part]` | panel |
| `[data-orientation]` | The orientation of the panel |
| `[data-dragging]` | Present when in the dragging state |
| `[data-id]` |  |
| `[data-index]` | The index of the item |


**ResizeTriggerIndicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ResizeTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `id` | ``${string}:${string}`` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `disabled` | `boolean` | No |  |


**ResizeTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | splitter |
| `[data-part]` | resize-trigger |
| `[data-id]` |  |
| `[data-orientation]` | The orientation of the resizetrigger |
| `[data-focus]` | Present when focused |
| `[data-dragging]` | Present when in the dragging state |
| `[data-disabled]` | Present when disabled |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseSplitterReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `dragging` | `boolean` | Whether the splitter is currently being resized. |
| `orientation` | `"horizontal" | "vertical"` | The orientation of the splitter. |
| `getSizes` | `() => number[]` | Returns the current sizes of the panels. |
| `setSizes` | `(size: number[]) => void` | Sets the sizes of the panels. |
| `getItems` | `() => SplitterItem[]` | Returns the items of the splitter. |
| `getPanels` | `() => PanelData[]` | Returns the panels of the splitter. |
| `getPanelById` | `(id: string) => PanelData` | Returns the panel with the specified id. |
| `getPanelSize` | `(id: string) => number` | Returns the size of the specified panel. |
| `isPanelCollapsed` | `(id: string) => boolean` | Returns whether the specified panel is collapsed. |
| `isPanelExpanded` | `(id: string) => boolean` | Returns whether the specified panel is expanded. |
| `collapsePanel` | `(id: string) => void` | Collapses the specified panel. |
| `expandPanel` | `(id: string, minSize?: number) => void` | Expands the specified panel. |
| `resizePanel` | `(id: string, unsafePanelSize: number) => void` | Resizes the specified panel. |
| `getLayout` | `() => string` | Returns the layout of the splitter. |
| `resetSizes` | `VoidFunction` | Resets the splitter to its initial state. |
| `getResizeTriggerState` | `(props: ResizeTriggerProps) => ResizeTriggerState` | Returns the state of the resize trigger. |


## Accessibility

Complies with the [Window Splitter WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/).


# Steps 



## Anatomy



```tsx
<Steps.Root>
  <Steps.List>
    <Steps.Item>
      <Steps.Trigger>
        <Steps.Indicator />
      </Steps.Trigger>
      <Steps.Separator />
    </Steps.Item>
  </Steps.List>
  <Steps.Content />
  <Steps.CompletedContent />
  <Steps.PrevTrigger />
  <Steps.NextTrigger />
</Steps.Root>
```

## Examples

### Basic

Here's a basic example of the `Steps` component.

```ripple
import { Steps } from 'ark-ripple/steps';
import button from 'styles/button.module.css';
import styles from 'styles/steps.module.css';

const items = [
  { value: 'first', title: 'First', description: 'Contact Info' },
  { value: 'second', title: 'Second', description: 'Date & Time' },
  { value: 'third', title: 'Third', description: 'Select Rooms' },
];

export component Basic() {
  <Steps.Root class={styles.Root} count={items.length}>
    <Steps.List class={styles.List}>
      for (const item of items; index index; key item.value) {
        <Steps.Item class={styles.Item} {index}>
          <Steps.Trigger class={styles.Trigger}>
            <Steps.Indicator class={styles.Indicator}>{index + 1}</Steps.Indicator>
            <span>{item.title}</span>
          </Steps.Trigger>
          <Steps.Separator class={styles.Separator} />
        </Steps.Item>
      }
    </Steps.List>

    for (const item of items; index index; key item.value) {
      <Steps.Content class={styles.Content} {index}>
        {item.title}
        {' - '}
        {item.description}
      </Steps.Content>
    }

    <Steps.CompletedContent class={styles.CompletedContent}>
      {'Steps Complete - Thank you for filling out the form!'}
    </Steps.CompletedContent>

    <div class={styles.Actions}>
      <Steps.PrevTrigger class={button.Root}>{'Back'}</Steps.PrevTrigger>
      <Steps.NextTrigger class={button.Root} data-variant="solid">{'Next'}</Steps.NextTrigger>
    </div>
  </Steps.Root>
}
```

### Controlled

Using the `RootProvider` component, you can control the active step by using the `step` prop and handling the
`onStepChange` event.

**Example: controlled**

```ripple
import { Steps } from 'ark-ripple/steps';
import { track } from 'ripple';
import button from 'styles/button.module.css';
import styles from 'styles/steps.module.css';

const items = [
  { value: 'first', title: 'First', description: 'Contact Info' },
  { value: 'second', title: 'Second', description: 'Date & Time' },
  { value: 'third', title: 'Third', description: 'Select Rooms' },
];

export component Controlled() {
  let step = track(0);

  <div class="stack">
    <output>
      {'current step: '}
      {@step + 1}
    </output>

    <Steps.Root
      class={styles.Root}
      count={items.length}
      {step}
      onStepChange={(details) => {
        @step = details.step;
      }}
    >
      <Steps.List class={styles.List}>
        for (const item of items; index index; key item.value) {
          <Steps.Item class={styles.Item} {index}>
            <Steps.Trigger class={styles.Trigger}>
              <Steps.Indicator class={styles.Indicator}>{index + 1}</Steps.Indicator>
              <span>{item.title}</span>
            </Steps.Trigger>
            <Steps.Separator class={styles.Separator} />
          </Steps.Item>
        }
      </Steps.List>

      for (const item of items; index index; key item.value) {
        <Steps.Content class={styles.Content} {index}>
          {item.title}
          {' - '}
          {item.description}
        </Steps.Content>
      }

      <Steps.CompletedContent class={styles.CompletedContent}>
        {'Steps Complete - Thank you for filling out the form!'}
      </Steps.CompletedContent>

      <div class={styles.Actions}>
        <Steps.PrevTrigger class={button.Root}>{'Back'}</Steps.PrevTrigger>
        <Steps.NextTrigger class={button.Root} data-variant="solid">{'Next'}</Steps.NextTrigger>
      </div>
    </Steps.Root>
  </div>
}

```

### Root Provider

An alternative way to control the steps is to use the `RootProvider` component and the `useSteps` hook. This way you can
access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { Steps, useSteps } from 'ark-ripple/steps';
import button from 'styles/button.module.css';
import styles from 'styles/steps.module.css';

const items = [
  { value: 'first', title: 'First', description: 'Contact Info' },
  { value: 'second', title: 'Second', description: 'Date & Time' },
  { value: 'third', title: 'Third', description: 'Select Rooms' },
];

export component RootProvider() {
  const stepsApi = useSteps({ count: items.length });

  <div class="stack">
    <output>
      {'current step: '}
      {@stepsApi.value + 1}
    </output>

    <Steps.RootProvider class={styles.Root} value={stepsApi}>
      <Steps.List class={styles.List}>
        for (const item of items; index index; key item.value) {
          <Steps.Item class={styles.Item} {index}>
            <Steps.Trigger class={styles.Trigger}>
              <Steps.Indicator class={styles.Indicator}>{index + 1}</Steps.Indicator>
              <span>{item.title}</span>
            </Steps.Trigger>
            <Steps.Separator class={styles.Separator} />
          </Steps.Item>
        }
      </Steps.List>

      for (const item of items; index index; key item.value) {
        <Steps.Content class={styles.Content} {index}>
          {item.title}
          {' - '}
          {item.description}
        </Steps.Content>
      }

      <Steps.CompletedContent class={styles.CompletedContent}>
        {'Steps Complete - Thank you for filling out the form!'}
      </Steps.CompletedContent>

      <div class={styles.Actions}>
        <Steps.PrevTrigger class={button.Root}>{'Back'}</Steps.PrevTrigger>
        <Steps.NextTrigger class={button.Root} data-variant="solid">{'Next'}</Steps.NextTrigger>
      </div>
    </Steps.RootProvider>
  </div>
}

```

### Vertical

Use the `orientation` prop to display the steps vertically.

**Example: vertical**

```ripple
import { Steps } from 'ark-ripple/steps';
import button from 'styles/button.module.css';
import styles from 'styles/steps.module.css';

const items = [
  { value: 'first', title: 'First', description: 'Contact Info' },
  { value: 'second', title: 'Second', description: 'Date & Time' },
  { value: 'third', title: 'Third', description: 'Select Rooms' },
];

export component Vertical() {
  <Steps.Root class={styles.Root} count={items.length} orientation="vertical">
    <Steps.List class={styles.List}>
      for (const item of items; index index; key item.value) {
        <Steps.Item class={styles.Item} {index}>
          <Steps.Trigger class={styles.Trigger}>
            <Steps.Indicator class={styles.Indicator}>{index + 1}</Steps.Indicator>
            <span>{item.title}</span>
          </Steps.Trigger>
          <Steps.Separator class={styles.Separator} />
        </Steps.Item>
      }
    </Steps.List>

    for (const item of items; index index; key item.value) {
      <Steps.Content class={styles.Content} {index}>
        <div class="vstack">
          <span>
            {item.title}
            {' - '}
            {item.description}
          </span>
          <div class={styles.Actions}>
            <Steps.PrevTrigger class={button.Root}>{'Back'}</Steps.PrevTrigger>
            <Steps.NextTrigger class={button.Root} data-variant="solid">{'Next'}</Steps.NextTrigger>
          </div>
        </div>
      </Steps.Content>
    }

    <Steps.CompletedContent class={styles.CompletedContent}>
      <div class="vstack">
        <span>{'Steps Complete - Thank you for filling out the form!'}</span>
        <Steps.PrevTrigger class={button.Root}>{'Back'}</Steps.PrevTrigger>
      </div>
    </Steps.CompletedContent>
  </Steps.Root>
}

```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `count` | `number` | No | The total number of steps |
| `defaultStep` | `number` | No | The initial value of the stepper when rendered.
Use when you don't need to control the value of the stepper. |
| `ids` | `ElementIds` | No | The custom ids for the stepper elements |
| `isStepSkippable` | `(index: number) => boolean` | No | Whether a step can be skipped during navigation.
Skippable steps are bypassed when using next/prev. |
| `isStepValid` | `(index: number) => boolean` | No | Whether a step is valid. Invalid steps block forward navigation in linear mode. |
| `linear` | `boolean` | No | If `true`, the stepper requires the user to complete the steps in order |
| `onStepChange` | `(details: StepChangeDetails) => void` | No | Callback to be called when the value changes |
| `onStepComplete` | `VoidFunction` | No | Callback to be called when a step is completed |
| `onStepInvalid` | `(details: StepInvalidDetails) => void` | No | Called when navigation is blocked due to an invalid step. |
| `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the stepper |
| `step` | `number` | No | The controlled value of the stepper |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | root |
| `[data-orientation]` | The orientation of the steps |


**Root CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--percent` | The percent value for the Root |


**CompletedContent Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | content |
| `[data-state]` | "open" | "closed" |
| `[data-orientation]` | The orientation of the content |


**Indicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Indicator Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | indicator |
| `[data-complete]` | Present when the indicator value is complete |
| `[data-current]` | Present when current |
| `[data-incomplete]` |  |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Item Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | item |
| `[data-orientation]` | The orientation of the item |
| `[data-skippable]` |  |


**List Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**List Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | list |
| `[data-orientation]` | The orientation of the list |


**NextTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**PrevTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Progress Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Progress Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | progress |
| `[data-complete]` | Present when the progress value is complete |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseStepsReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Separator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Separator Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | separator |
| `[data-orientation]` | The orientation of the separator |
| `[data-complete]` | Present when the separator value is complete |
| `[data-current]` | Present when current |
| `[data-incomplete]` |  |


**Trigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | trigger |
| `[data-state]` | "open" | "closed" |
| `[data-orientation]` | The orientation of the trigger |
| `[data-complete]` | Present when the trigger value is complete |
| `[data-current]` | Present when current |
| `[data-incomplete]` |  |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `value` | `number` | The value of the stepper. |
| `percent` | `number` | The percentage of the stepper. |
| `count` | `number` | The total number of steps. |
| `hasNextStep` | `boolean` | Whether the stepper has a next step. |
| `hasPrevStep` | `boolean` | Whether the stepper has a previous step. |
| `isCompleted` | `boolean` | Whether the stepper is completed. |
| `isStepValid` | `(index: number) => boolean` | Check if a specific step is valid (lazy evaluation) |
| `isStepSkippable` | `(index: number) => boolean` | Check if a specific step can be skipped |
| `setStep` | `(step: number) => void` | Function to set the value of the stepper. |
| `goToNextStep` | `VoidFunction` | Function to go to the next step. |
| `goToPrevStep` | `VoidFunction` | Function to go to the previous step. |
| `resetStep` | `VoidFunction` | Function to go to reset the stepper. |
| `getItemState` | `(props: ItemProps) => ItemState` | Returns the state of the item at the given index. |



# Switch 



## Anatomy



```tsx
<Switch.Root>
  <Switch.Control>
    <Switch.Thumb />
  </Switch.Control>
  <Switch.Label />
  <Switch.HiddenInput />
</Switch.Root>
```

## Examples

**Example: basic**

```ripple
import { Switch } from 'ark-ripple/switch';
import styles from 'styles/switch.module.css';

export component Basic() {
  <Switch.Root class={styles.Root}>
    <Switch.Control class={styles.Control}>
      <Switch.Thumb class={styles.Thumb} />
    </Switch.Control>
    <Switch.Label class={styles.Label}>{'Label'}</Switch.Label>
    <Switch.HiddenInput />
  </Switch.Root>
}

```

### Controlled

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:

**Example: controlled**

```ripple
import { Switch } from 'ark-ripple/switch';
import { track } from 'ripple';
import styles from 'styles/switch.module.css';

export component Controlled() {
  let checked = track(false);

  <Switch.Root
    class={styles.Root}
    {checked}
    onCheckedChange={(e) => {
      @checked = e.checked;
    }}
  >
    <Switch.Control class={styles.Control}>
      <Switch.Thumb class={styles.Thumb} />
    </Switch.Control>
    <Switch.Label class={styles.Label}>{'Label'}</Switch.Label>
    <Switch.HiddenInput />
  </Switch.Root>
}

```

### Root Provider

An alternative way to control the switch is to use the `RootProvider` component and the `useSwitch` hook. This way you
can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { Switch, useSwitch } from 'ark-ripple/switch';
import button from 'styles/button.module.css';
import styles from 'styles/switch.module.css';

export component RootProvider() {
  const api = useSwitch();

  <div class="stack">
    <button
      class={button.Root}
      onClick={() => {
        @api.toggleChecked();
      }}
    >
      {'Toggle'}
    </button>

    <Switch.RootProvider class={styles.Root} value={api}>
      <Switch.Control class={styles.Control}>
        <Switch.Thumb class={styles.Thumb} />
      </Switch.Control>
      <Switch.Label class={styles.Label}>{'Label'}</Switch.Label>
      <Switch.HiddenInput />
    </Switch.RootProvider>
  </div>
}

```

### Field

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.

**Example: with-field**

```ripple
import { Field } from 'ark-ripple/field';
import { Switch } from 'ark-ripple/switch';
import field from 'styles/field.module.css';
import styles from 'styles/switch.module.css';

export component WithField() {
  <Field.Root class={field.Root}>
    <Switch.Root class={styles.Root}>
      <Switch.Control class={styles.Control}>
        <Switch.Thumb class={styles.Thumb} />
      </Switch.Control>
      <Switch.Label class={styles.Label}>{'Label'}</Switch.Label>
      <Switch.HiddenInput />
    </Switch.Root>
    <Field.HelperText class={field.HelperText}>{'Additional Info'}</Field.HelperText>
    <Field.ErrorText class={field.ErrorText}>{'Error Info'}</Field.ErrorText>
  </Field.Root>
}

```

### Context

Access the switch's state with `Switch.Context` or the `useSwitchContext` hook. This lets you customize the component
based on its current state:

**Example: context**

```ripple
import { Switch } from 'ark-ripple/switch';
import styles from 'styles/switch.module.css';

export component Context() {
  <Switch.Root class={styles.Root}>
    <Switch.Control class={styles.Control}>
      <Switch.Thumb class={styles.Thumb} />
    </Switch.Control>
    <Switch.Context>
      component children({ context }) {
        <Switch.Label class={styles.Label}>
          {'Feature is '}
          {@context.checked ? 'enabled' : 'disabled'}
        </Switch.Label>
      }
    </Switch.Context>
    <Switch.HiddenInput />
  </Switch.Root>
}

```

## Guides

### asChild

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.

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `checked` | `boolean` | No | The controlled checked state of the switch |
| `disabled` | `boolean` | No | Whether the switch is disabled. |
| `ids` | `Partial<{ root: string; hiddenInput: string; control: string; label: string; thumb: string }>` | No | The ids of the elements in the switch. Useful for composition. |
| `invalid` | `boolean` | No | If `true`, the switch is marked as invalid. |
| `label` | `string` | No | Specifies the localized strings that identifies the accessibility elements and their states |
| `name` | `string` | No | The name of the input field in a switch
(Useful for form submission). |
| `onCheckedChange` | `(details: CheckedChangeDetails) => void` | No | Function to call when the switch is clicked. |
| `readOnly` | `boolean` | No | Whether the switch is read-only |
| `required` | `boolean` | No | If `true`, the switch input is marked as required, |
| `value` | `string | number` | No | The value of switch input. Useful for form submission. |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-active]` | Present when active or pressed |
| `[data-focus]` | Present when focused |
| `[data-focus-visible]` | Present when focused with keyboard |
| `[data-readonly]` | Present when read-only |
| `[data-hover]` | Present when hovered |
| `[data-disabled]` | Present when disabled |
| `[data-state]` | "checked" | "unchecked" |
| `[data-invalid]` | Present when invalid |
| `[data-required]` | Present when required |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-active]` | Present when active or pressed |
| `[data-focus]` | Present when focused |
| `[data-focus-visible]` | Present when focused with keyboard |
| `[data-readonly]` | Present when read-only |
| `[data-hover]` | Present when hovered |
| `[data-disabled]` | Present when disabled |
| `[data-state]` | "checked" | "unchecked" |
| `[data-invalid]` | Present when invalid |
| `[data-required]` | Present when required |


**HiddenInput Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-active]` | Present when active or pressed |
| `[data-focus]` | Present when focused |
| `[data-focus-visible]` | Present when focused with keyboard |
| `[data-readonly]` | Present when read-only |
| `[data-hover]` | Present when hovered |
| `[data-disabled]` | Present when disabled |
| `[data-state]` | "checked" | "unchecked" |
| `[data-invalid]` | Present when invalid |
| `[data-required]` | Present when required |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseSwitchReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Thumb Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Thumb Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-active]` | Present when active or pressed |
| `[data-focus]` | Present when focused |
| `[data-focus-visible]` | Present when focused with keyboard |
| `[data-readonly]` | Present when read-only |
| `[data-hover]` | Present when hovered |
| `[data-disabled]` | Present when disabled |
| `[data-state]` | "checked" | "unchecked" |
| `[data-invalid]` | Present when invalid |
| `[data-required]` | Present when required |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `checked` | `boolean` | Whether the switch is checked |
| `disabled` | `boolean` | Whether the switch is disabled |
| `focused` | `boolean` | Whether the switch is focused |
| `setChecked` | `(checked: boolean) => void` | Sets the checked state of the switch. |
| `toggleChecked` | `VoidFunction` | Toggles the checked state of the switch. |


## 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



```tsx
<Tabs.Root>
  <Tabs.List>
    <Tabs.Trigger />
    <Tabs.Indicator />
  </Tabs.List>
  <Tabs.Content />
</Tabs.Root>
```

## Examples

**Example: basic**

```ripple
import { Tabs } from 'ark-ripple/tabs';
import styles from 'styles/tabs.module.css';

export component Basic() {
  <Tabs.Root class={styles.Root} defaultValue="account">
    <Tabs.List class={styles.List}>
      <Tabs.Trigger class={styles.Trigger} value="account">{'Account'}</Tabs.Trigger>
      <Tabs.Trigger class={styles.Trigger} value="password">{'Password'}</Tabs.Trigger>
      <Tabs.Trigger class={styles.Trigger} value="billing">{'Billing'}</Tabs.Trigger>
    </Tabs.List>
    <Tabs.Content class={styles.Content} value="account">
      {'Make changes to your account here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="password">
      {'Change your password here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="billing">
      {'Manage your billing and payment details.'}
    </Tabs.Content>
  </Tabs.Root>
}

```

### Controlled

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:

**Example: controlled**

```ripple
import { Tabs } from 'ark-ripple/tabs';
import { track } from 'ripple';
import styles from 'styles/tabs.module.css';

export component Controlled() {
  let value = track<string | null>('account');

  <Tabs.Root
    class={styles.Root}
    {value}
    onValueChange={(e) => {
      @value = e.value;
    }}
  >
    <Tabs.List class={styles.List}>
      <Tabs.Trigger class={styles.Trigger} value="account">{'Account'}</Tabs.Trigger>
      <Tabs.Trigger class={styles.Trigger} value="password">{'Password'}</Tabs.Trigger>
      <Tabs.Trigger class={styles.Trigger} value="billing">{'Billing'}</Tabs.Trigger>
    </Tabs.List>
    <Tabs.Content class={styles.Content} value="account">
      {'Make changes to your account here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="password">
      {'Change your password here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="billing">
      {'Manage your billing and payment details.'}
    </Tabs.Content>
  </Tabs.Root>
}

```

### Root Provider

An alternative way to control the tabs is to use the `RootProvider` component and the `useTabs` hook. This way you can
access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { Tabs, useTabs } from 'ark-ripple/tabs';
import styles from 'styles/tabs.module.css';

export component RootProvider() {
  const api = useTabs({ defaultValue: 'account' });

  <div class="stack">
    <output>
      {'selected: '}
      {@api.value}
    </output>
    <Tabs.RootProvider class={styles.Root} value={api}>
      <Tabs.List class={styles.List}>
        <Tabs.Trigger class={styles.Trigger} value="account">{'Account'}</Tabs.Trigger>
        <Tabs.Trigger class={styles.Trigger} value="password">{'Password'}</Tabs.Trigger>
        <Tabs.Trigger class={styles.Trigger} value="billing">{'Billing'}</Tabs.Trigger>
      </Tabs.List>
      <Tabs.Content class={styles.Content} value="account">
        {'Make changes to your account here.'}
      </Tabs.Content>
      <Tabs.Content class={styles.Content} value="password">
        {'Change your password here.'}
      </Tabs.Content>
      <Tabs.Content class={styles.Content} value="billing">
        {'Manage your billing and payment details.'}
      </Tabs.Content>
    </Tabs.RootProvider>
  </div>
}

```

### Indicator

To provide a visual cue for the selected tab, use the `Tabs.Indicator` component:

**Example: indicator**

```ripple
import { Tabs } from 'ark-ripple/tabs';
import styles from 'styles/tabs.module.css';

export component Indicator() {
  <Tabs.Root class={styles.Root} defaultValue="account">
    <Tabs.List class={styles.List}>
      <Tabs.Trigger class={styles.TriggerIndicator} value="account">{'Account'}</Tabs.Trigger>
      <Tabs.Trigger class={styles.TriggerIndicator} value="password">{'Password'}</Tabs.Trigger>
      <Tabs.Trigger class={styles.TriggerIndicator} value="billing">{'Billing'}</Tabs.Trigger>
      <Tabs.Indicator class={styles.Indicator} />
    </Tabs.List>
    <Tabs.Content class={styles.Content} value="account">
      {'Make changes to your account here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="password">
      {'Change your password here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="billing">
      {'Manage your billing and payment details.'}
    </Tabs.Content>
  </Tabs.Root>
}

```

### Disabled

To disable a tab, simply pass the `disabled` prop to the `Tabs.Trigger` component:

**Example: disabled-tab**

```ripple
import { Tabs } from 'ark-ripple/tabs';
import styles from 'styles/tabs.module.css';

export component DisabledTab() {
  <Tabs.Root class={styles.Root} defaultValue="account">
    <Tabs.List class={styles.List}>
      <Tabs.Trigger class={styles.Trigger} value="account">{'Account'}</Tabs.Trigger>
      <Tabs.Trigger class={styles.Trigger} value="password" disabled>{'Password'}</Tabs.Trigger>
      <Tabs.Trigger class={styles.Trigger} value="billing">{'Billing'}</Tabs.Trigger>
    </Tabs.List>
    <Tabs.Content class={styles.Content} value="account">
      {'Make changes to your account here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="password">
      {'Change your password here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="billing">
      {'Manage your billing and payment details.'}
    </Tabs.Content>
  </Tabs.Root>
}

```

### Vertical

The default orientation of the tabs is `horizontal`. To change the orientation, set the `orientation` prop to
`vertical`.

**Example: vertical**

```ripple
import { Tabs } from 'ark-ripple/tabs';
import styles from 'styles/tabs.module.css';

export component Vertical() {
  <Tabs.Root class={styles.Root} orientation="vertical" defaultValue="account">
    <Tabs.List class={styles.List}>
      <Tabs.Trigger class={styles.Trigger} value="account">{'Account'}</Tabs.Trigger>
      <Tabs.Trigger class={styles.Trigger} value="password">{'Password'}</Tabs.Trigger>
      <Tabs.Trigger class={styles.Trigger} value="billing">{'Billing'}</Tabs.Trigger>
    </Tabs.List>
    <Tabs.Content class={styles.Content} value="account">
      {'Make changes to your account here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="password">
      {'Change your password here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="billing">
      {'Manage your billing and payment details.'}
    </Tabs.Content>
  </Tabs.Root>
}

```

### Lazy Mount

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.

**Example: lazy-mount**

```ripple
import { Tabs } from 'ark-ripple/tabs';
import styles from 'styles/tabs.module.css';

export component LazyMount() {
  <Tabs.Root class={styles.Root} lazyMount unmountOnExit defaultValue="account">
    <Tabs.List class={styles.List}>
      <Tabs.Trigger class={styles.TriggerIndicator} value="account">{'Account'}</Tabs.Trigger>
      <Tabs.Trigger class={styles.TriggerIndicator} value="password">{'Password'}</Tabs.Trigger>
      <Tabs.Trigger class={styles.TriggerIndicator} value="billing">{'Billing'}</Tabs.Trigger>
      <Tabs.Indicator class={styles.Indicator} />
    </Tabs.List>
    <Tabs.Content class={styles.Content} value="account">
      {'Make changes to your account here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="password">
      {'Change your password here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="billing">
      {'Manage your billing and payment details.'}
    </Tabs.Content>
  </Tabs.Root>
}

```

### 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

<kbd>Enter</kbd> key or by clicking on the tab.

**Example: manual-activation**

```ripple
import { Tabs } from 'ark-ripple/tabs';
import styles from 'styles/tabs.module.css';

export component ManualActivation() {
  <Tabs.Root class={styles.Root} activationMode="manual" defaultValue="account">
    <Tabs.List class={styles.List}>
      <Tabs.Trigger class={styles.Trigger} value="account">{'Account'}</Tabs.Trigger>
      <Tabs.Trigger class={styles.Trigger} value="password">{'Password'}</Tabs.Trigger>
      <Tabs.Trigger class={styles.Trigger} value="billing">{'Billing'}</Tabs.Trigger>
    </Tabs.List>
    <Tabs.Content class={styles.Content} value="account">
      {'Make changes to your account here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="password">
      {'Change your password here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="billing">
      {'Manage your billing and payment details.'}
    </Tabs.Content>
  </Tabs.Root>
}

```

### Links

Use the `asChild` prop to render tab triggers as anchor links. This is useful for SEO and allows tabs to work with
browser navigation.

**Example: links**

```ripple
import { Tabs } from 'ark-ripple/tabs';
import styles from 'styles/tabs.module.css';

export component Links() {
  <Tabs.Root class={styles.Root} defaultValue="account">
    <Tabs.List class={styles.List}>
      <Tabs.Trigger class={styles.Trigger} value="account">
        component asChild({ propsFn }) {
          <a {...propsFn({ href: '#account' })}>{'Account'}</a>
        }
      </Tabs.Trigger>
      <Tabs.Trigger class={styles.Trigger} value="password">
        component asChild({ propsFn }) {
          <a {...propsFn({ href: '#password' })}>{'Password'}</a>
        }
      </Tabs.Trigger>
      <Tabs.Trigger class={styles.Trigger} value="billing">
        component asChild({ propsFn }) {
          <a {...propsFn({ href: '#billing' })}>{'Billing'}</a>
        }
      </Tabs.Trigger>
    </Tabs.List>
    <Tabs.Content class={styles.Content} value="account">
      {'Make changes to your account here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="password">
      {'Change your password here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="billing">
      {'Manage your billing and payment details.'}
    </Tabs.Content>
  </Tabs.Root>
}

```

## Guides

### Router Integration

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/<framework>/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 (
    <Tabs.Root
      value={activeTab}
      onValueChange={({ value }) => {
        navigate(`/${value === 'home' ? '' : value}`)
      }}
    >
      <Tabs.List>
        <Tabs.Trigger asChild value="home">
          <Link to="">Home</Link>
        </Tabs.Trigger>
        <Tabs.Trigger asChild value="page-1">
          <Link to="page-1">Page 1</Link>
        </Tabs.Trigger>
        <Tabs.Trigger asChild value="page-2">
          <Link to="page-2">Page 2</Link>
        </Tabs.Trigger>
      </Tabs.List>
    </Tabs.Root>
  )
}
```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `activationMode` | `'manual' | 'automatic'` | No | The activation mode of the tabs. Can be `manual` or `automatic`
- `manual`: Tabs are activated when clicked or press `enter` key.
- `automatic`: Tabs are activated when receiving focus |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `composite` | `boolean` | No | Whether the tab is composite |
| `defaultValue` | `string` | No | The initial selected tab value when rendered.
Use when you don't need to control the selected tab value. |
| `deselectable` | `boolean` | No | Whether the active tab can be deselected when clicking on it. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{
  root: string
  trigger: (value: string) => string
  list: string
  content: (value: string) => string
  indicator: string
}>` | No | The ids of the elements in the tabs. Useful for composition. |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `loopFocus` | `boolean` | No | Whether the keyboard navigation will loop from last tab to first, and vice versa. |
| `navigate` | `(details: NavigateDetails) => void` | No | Function to navigate to the selected tab when clicking on it.
Useful if tab triggers are anchor elements. |
| `onFocusChange` | `(details: FocusChangeDetails) => void` | No | Callback to be called when the focused tab changes |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | Callback to be called when the selected/active tab changes |
| `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the tabs. Can be `horizontal` or `vertical`
- `horizontal`: only left and right arrow key navigation will work.
- `vertical`: only up and down arrow key navigation will work. |
| `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |
| `value` | `string` | No | The controlled selected tab value |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tabs |
| `[data-part]` | root |
| `[data-orientation]` | The orientation of the tabs |
| `[data-focus]` | Present when focused |


**TabContent Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `string` | Yes | The value of the tab |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**TabIndicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**TabList Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**TabTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `string` | Yes | The value of the tab |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `disabled` | `boolean` | No | Whether the tab is disabled |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseTabsReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `value` | `string` | The current value of the tabs. |
| `focusedValue` | `string` | The value of the tab that is currently focused. |
| `setValue` | `(value: string) => void` | Sets the value of the tabs. |
| `clearValue` | `VoidFunction` | Clears the value of the tabs. |
| `setIndicatorRect` | `(value: string) => void` | Sets the indicator rect to the tab with the given value |
| `syncTabIndex` | `VoidFunction` | Synchronizes the tab index of the content element.
Useful when rendering tabs within a select or combobox |
| `focus` | `VoidFunction` | Set focus on the selected tab trigger |
| `selectNext` | `(fromValue?: string) => void` | Selects the next tab |
| `selectPrev` | `(fromValue?: string) => void` | Selects the previous tab |
| `getTriggerState` | `(props: TriggerProps) => TriggerState` | Returns the state of the trigger with the given props |


## 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



```tsx
<TagsInput.Root>
  <TagsInput.Label />
  <TagsInput.Control>
    <TagsInput.Item>
      <TagsInput.ItemPreview>
        <TagsInput.ItemText />
        <TagsInput.ItemDeleteTrigger />
      </TagsInput.ItemPreview>
      <TagsInput.ItemInput />
    </TagsInput.Item>
    <TagsInput.Input />
    <TagsInput.ClearTrigger />
  </TagsInput.Control>
  <TagsInput.HiddenInput />
</TagsInput.Root>
```

## Examples

**Example: basic**

```ripple
import { TagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import styles from 'styles/tags-input.module.css';

export component Basic() {
  <TagsInput.Root class={styles.Root}>
    <TagsInput.Context>
      component children({ context }) {
        <TagsInput.Label class={styles.Label}>{'Frameworks'}</TagsInput.Label>
        <TagsInput.Control class={styles.Control}>
          for (const value of @context.value; index i; key value) {
            <TagsInput.Item class={styles.Item} index={i} {value}>
              <TagsInput.ItemPreview class={styles.ItemPreview}>
                <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                  <X />
                </TagsInput.ItemDeleteTrigger>
              </TagsInput.ItemPreview>
              <TagsInput.ItemInput class={styles.ItemInput} />
            </TagsInput.Item>
          }
          <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
          <TagsInput.ClearTrigger class={styles.ClearTrigger}>
            <X />
          </TagsInput.ClearTrigger>
        </TagsInput.Control>
      }
    </TagsInput.Context>
    <TagsInput.HiddenInput />
  </TagsInput.Root>
}

```

### Controlled

Use the `value` and `onValueChange` props to programmatically control the tags input's state. This allows you to manage
the tags array externally and respond to changes.

**Example: controlled**

```ripple
import { TagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/tags-input.module.css';

export component Controlled() {
  let value = track<string[]>(['React', 'Solid']);

  <TagsInput.Root
    class={styles.Root}
    {value}
    onValueChange={(details) => {
      @value = details.value;
    }}
  >
    <TagsInput.Context>
      component children({ context }) {
        <TagsInput.Label class={styles.Label}>{'Frameworks'}</TagsInput.Label>
        <TagsInput.Control class={styles.Control}>
          for (const val of @context.value; index i; key val) {
            <TagsInput.Item class={styles.Item} index={i} value={val}>
              <TagsInput.ItemPreview class={styles.ItemPreview}>
                <TagsInput.ItemText class={styles.ItemText}>{val}</TagsInput.ItemText>
                <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                  <X />
                </TagsInput.ItemDeleteTrigger>
              </TagsInput.ItemPreview>
              <TagsInput.ItemInput class={styles.ItemInput} />
            </TagsInput.Item>
          }
          <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
          <TagsInput.ClearTrigger class={styles.ClearTrigger}>
            <X />
          </TagsInput.ClearTrigger>
        </TagsInput.Control>
      }
    </TagsInput.Context>
    <TagsInput.HiddenInput />
  </TagsInput.Root>
}

```

### Controlled Input Value

Use the `inputValue` and `onInputValueChange` props to control the text input field independently. This is useful for
clearing the input or pre-filling it programmatically.

**Example: controlled-input-value**

```ripple
import { TagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/tags-input.module.css';
import button from 'styles/button.module.css';

export component ControlledInputValue() {
  let inputValue = track('');

  <div class="stack">
    <div style={{ display: 'flex', gap: '8px', alignItems: 'center' }}>
      <button
        class={button.Root}
        type="button"
        onClick={() => {
          @inputValue = 'React';
        }}
      >
        {'Set to "React"'}
      </button>
      <button
        class={button.Root}
        type="button"
        onClick={() => {
          @inputValue = '';
        }}
      >
        {'Clear Input'}
      </button>
      <span style={{ fontSize: '14px' }}>
        {'Current: "'}
        {@inputValue}
        {'"'}
      </span>
    </div>

    <TagsInput.Root
      class={styles.Root}
      {inputValue}
      onInputValueChange={(details) => {
        @inputValue = details.inputValue;
      }}
    >
      <TagsInput.Context>
        component children({ context }) {
          <TagsInput.Label class={styles.Label}>{'Frameworks'}</TagsInput.Label>
          <TagsInput.Control class={styles.Control}>
            for (const value of @context.value; index i; key value) {
              <TagsInput.Item class={styles.Item} index={i} {value}>
                <TagsInput.ItemPreview class={styles.ItemPreview}>
                  <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                  <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                    <X />
                  </TagsInput.ItemDeleteTrigger>
                </TagsInput.ItemPreview>
                <TagsInput.ItemInput class={styles.ItemInput} />
              </TagsInput.Item>
            }
            <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
            <TagsInput.ClearTrigger class={styles.ClearTrigger}>
              <X />
            </TagsInput.ClearTrigger>
          </TagsInput.Control>
        }
      </TagsInput.Context>
      <TagsInput.HiddenInput />
    </TagsInput.Root>
  </div>
}

```

### Root Provider

An alternative way to control the tags input is to use the `RootProvider` component and the `useTagsInput` hook. This
way you can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { TagsInput, useTagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import styles from 'styles/tags-input.module.css';

export component RootProvider() {
  const tagsInput = useTagsInput();

  <div class="stack">
    <TagsInput.RootProvider class={styles.Root} value={tagsInput}>
      <TagsInput.Context>
        component children({ context }) {
          <TagsInput.Label class={styles.Label}>{'Frameworks'}</TagsInput.Label>
          <TagsInput.Control class={styles.Control}>
            for (const value of @context.value; index i; key value) {
              <TagsInput.Item class={styles.Item} index={i} {value}>
                <TagsInput.ItemPreview class={styles.ItemPreview}>
                  <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                  <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                    <X />
                  </TagsInput.ItemDeleteTrigger>
                </TagsInput.ItemPreview>
                <TagsInput.ItemInput class={styles.ItemInput} />
              </TagsInput.Item>
            }
            <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
            <TagsInput.ClearTrigger class={styles.ClearTrigger}>
              <X />
            </TagsInput.ClearTrigger>
          </TagsInput.Control>
        }
      </TagsInput.Context>
      <TagsInput.HiddenInput />
    </TagsInput.RootProvider>

    <output>
      {'values: '}
      {JSON.stringify(@tagsInput.value)}
    </output>
  </div>
}

```

### Field

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.

**Example: with-field**

```ripple
import { Field } from 'ark-ripple/field';
import { TagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import field from 'styles/field.module.css';
import styles from 'styles/tags-input.module.css';

export component WithField() {
  <Field.Root class={field.Root}>
    <TagsInput.Root class={styles.Root}>
      <TagsInput.Context>
        component children({ context }) {
          <TagsInput.Label class={styles.Label}>{'Frameworks'}</TagsInput.Label>
          <TagsInput.Control class={styles.Control}>
            for (const value of @context.value; index i; key value) {
              <TagsInput.Item class={styles.Item} index={i} {value}>
                <TagsInput.ItemPreview class={styles.ItemPreview}>
                  <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                  <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                    <X />
                  </TagsInput.ItemDeleteTrigger>
                </TagsInput.ItemPreview>
                <TagsInput.ItemInput class={styles.ItemInput} />
              </TagsInput.Item>
            }
            <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
            <TagsInput.ClearTrigger class={styles.ClearTrigger}>
              <X />
            </TagsInput.ClearTrigger>
          </TagsInput.Control>
        }
      </TagsInput.Context>
      <TagsInput.HiddenInput />
    </TagsInput.Root>
    <Field.HelperText class={field.HelperText}>{'Additional Info'}</Field.HelperText>
    <Field.ErrorText class={field.ErrorText}>{'Error Info'}</Field.ErrorText>
  </Field.Root>
}

```

### Max 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`.

**Example: max-with-overflow**

```ripple
import { TagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import styles from 'styles/tags-input.module.css';

export component MaxWithOverflow() {
  <TagsInput.Root class={styles.Root} max={3} allowOverflow>
    <TagsInput.Context>
      component children({ context }) {
        <TagsInput.Label class={styles.Label}>{'Frameworks'}</TagsInput.Label>
        <TagsInput.Control class={styles.Control}>
          for (const value of @context.value; index i; key value) {
            <TagsInput.Item class={styles.Item} index={i} {value}>
              <TagsInput.ItemPreview class={styles.ItemPreview}>
                <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                  <X />
                </TagsInput.ItemDeleteTrigger>
              </TagsInput.ItemPreview>
              <TagsInput.ItemInput class={styles.ItemInput} />
            </TagsInput.Item>
          }
          <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
          <TagsInput.ClearTrigger class={styles.ClearTrigger}>
            <X />
          </TagsInput.ClearTrigger>
        </TagsInput.Control>
      }
    </TagsInput.Context>
    <TagsInput.HiddenInput />
  </TagsInput.Root>
}

```

### Custom Delimiter

Use the `delimiter` prop with a regex pattern to specify multiple characters that can separate tags. By default, only
the Enter key creates tags.

**Example: delimiter**

```ripple
import { TagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import styles from 'styles/tags-input.module.css';

const DELIMITER_PATTERN = /[,;\s]/;

export component Delimiter() {
  <TagsInput.Root class={styles.Root} delimiter={DELIMITER_PATTERN}>
    <TagsInput.Context>
      component children({ context }) {
        <TagsInput.Label class={styles.Label}>
          {'Frameworks (add with comma, semicolon, or space)'}
        </TagsInput.Label>
        <TagsInput.Control class={styles.Control}>
          for (const value of @context.value; index i; key value) {
            <TagsInput.Item class={styles.Item} index={i} {value}>
              <TagsInput.ItemPreview class={styles.ItemPreview}>
                <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                  <X />
                </TagsInput.ItemDeleteTrigger>
              </TagsInput.ItemPreview>
              <TagsInput.ItemInput class={styles.ItemInput} />
            </TagsInput.Item>
          }
          <TagsInput.Input placeholder="Add tag" class={styles.Input} />
          <TagsInput.ClearTrigger class={styles.ClearTrigger}>
            <X />
          </TagsInput.ClearTrigger>
        </TagsInput.Control>
      }
    </TagsInput.Context>
    <TagsInput.HiddenInput />
  </TagsInput.Root>
}

```

### Disabled

Use the `disabled` prop to make the tags input non-interactive. Users won't be able to add, remove, or edit tags.

**Example: disabled**

```ripple
import { TagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import styles from 'styles/tags-input.module.css';

export component Disabled() {
  <TagsInput.Root class={styles.Root} defaultValue={['React', 'Solid', 'Vue']} disabled>
    <TagsInput.Context>
      component children({ context }) {
        <TagsInput.Label class={styles.Label}>{'Frameworks'}</TagsInput.Label>
        <TagsInput.Control class={styles.Control}>
          for (const value of @context.value; index i; key value) {
            <TagsInput.Item class={styles.Item} index={i} {value}>
              <TagsInput.ItemPreview class={styles.ItemPreview}>
                <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                  <X />
                </TagsInput.ItemDeleteTrigger>
              </TagsInput.ItemPreview>
              <TagsInput.ItemInput class={styles.ItemInput} />
            </TagsInput.Item>
          }
          <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
          <TagsInput.ClearTrigger class={styles.ClearTrigger}>
            <X />
          </TagsInput.ClearTrigger>
        </TagsInput.Control>
      }
    </TagsInput.Context>
    <TagsInput.HiddenInput />
  </TagsInput.Root>
}

```

### Invalid

Use the `invalid` prop to mark the tags input as invalid for form validation purposes.

**Example: invalid**

```ripple
import { TagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import styles from 'styles/tags-input.module.css';

export component Invalid() {
  <TagsInput.Root class={styles.Root} invalid>
    <TagsInput.Context>
      component children({ context }) {
        <TagsInput.Label class={styles.Label}>{'Frameworks'}</TagsInput.Label>
        <TagsInput.Control class={styles.Control}>
          for (const value of @context.value; index i; key value) {
            <TagsInput.Item class={styles.Item} index={i} {value}>
              <TagsInput.ItemPreview class={styles.ItemPreview}>
                <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                  <X />
                </TagsInput.ItemDeleteTrigger>
              </TagsInput.ItemPreview>
              <TagsInput.ItemInput class={styles.ItemInput} />
            </TagsInput.Item>
          }
          <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
          <TagsInput.ClearTrigger class={styles.ClearTrigger}>
            <X />
          </TagsInput.ClearTrigger>
        </TagsInput.Control>
      }
    </TagsInput.Context>
    <TagsInput.HiddenInput />
  </TagsInput.Root>
}

```

### Max Length

Use the `maxLength` prop to limit the number of characters allowed per tag. This prevents users from creating overly
long tags.

**Example: max-tag-length**

```ripple
import { TagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import styles from 'styles/tags-input.module.css';

export component MaxTagLength() {
  <TagsInput.Root class={styles.Root} maxLength={10}>
    <TagsInput.Context>
      component children({ context }) {
        <TagsInput.Label class={styles.Label}>{'Frameworks (Max 10 characters)'}</TagsInput.Label>
        <TagsInput.Control class={styles.Control}>
          for (const value of @context.value; index i; key value) {
            <TagsInput.Item class={styles.Item} index={i} {value}>
              <TagsInput.ItemPreview class={styles.ItemPreview}>
                <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                  <X />
                </TagsInput.ItemDeleteTrigger>
              </TagsInput.ItemPreview>
              <TagsInput.ItemInput class={styles.ItemInput} />
            </TagsInput.Item>
          }
          <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
          <TagsInput.ClearTrigger class={styles.ClearTrigger}>
            <X />
          </TagsInput.ClearTrigger>
        </TagsInput.Control>
      }
    </TagsInput.Context>
    <TagsInput.HiddenInput />
  </TagsInput.Root>
}

```

### Read-only

Use the `readOnly` prop to make tags visible but not editable. Users can view tags but cannot add, remove, or modify
them.

**Example: readonly**

```ripple
import { TagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import styles from 'styles/tags-input.module.css';

export component Readonly() {
  <TagsInput.Root class={styles.Root} defaultValue={['React', 'Solid', 'Vue']} readOnly>
    <TagsInput.Context>
      component children({ context }) {
        <TagsInput.Label class={styles.Label}>{'Frameworks'}</TagsInput.Label>
        <TagsInput.Control class={styles.Control}>
          for (const value of @context.value; index i; key value) {
            <TagsInput.Item class={styles.Item} index={i} {value}>
              <TagsInput.ItemPreview class={styles.ItemPreview}>
                <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                  <X />
                </TagsInput.ItemDeleteTrigger>
              </TagsInput.ItemPreview>
              <TagsInput.ItemInput class={styles.ItemInput} />
            </TagsInput.Item>
          }
          <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
          <TagsInput.ClearTrigger class={styles.ClearTrigger}>
            <X />
          </TagsInput.ClearTrigger>
        </TagsInput.Control>
      }
    </TagsInput.Context>
    <TagsInput.HiddenInput />
  </TagsInput.Root>
}

```

### Validation

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.

**Example: validation**

```ripple
import { TagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import styles from 'styles/tags-input.module.css';

const TAG_PATTERN = /^[a-zA-Z0-9-]+$/;

const validateTag = ({
  value,
  inputValue,
}: {
  value: string[];
  inputValue: string;
}) => !!inputValue?.trim() && !value.includes(inputValue) && inputValue.length >= 3 &&
  TAG_PATTERN.test(inputValue);

export component Validation() {
  <TagsInput.Root class={styles.Root} validate={validateTag}>
    <TagsInput.Context>
      component children({ context }) {
        <TagsInput.Label class={styles.Label}>
          {'Frameworks (Min 3 chars, alphanumeric)'}
        </TagsInput.Label>
        <TagsInput.Control class={styles.Control}>
          for (const value of @context.value; index i; key value) {
            <TagsInput.Item class={styles.Item} index={i} {value}>
              <TagsInput.ItemPreview class={styles.ItemPreview}>
                <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                  <X />
                </TagsInput.ItemDeleteTrigger>
              </TagsInput.ItemPreview>
              <TagsInput.ItemInput class={styles.ItemInput} />
            </TagsInput.Item>
          }
          <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
          <TagsInput.ClearTrigger class={styles.ClearTrigger}>
            <X />
          </TagsInput.ClearTrigger>
        </TagsInput.Control>
      }
    </TagsInput.Context>
    <TagsInput.HiddenInput />
  </TagsInput.Root>
}

```

### 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.

**Example: blur-behavior**

```ripple
import { TagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import styles from 'styles/tags-input.module.css';

export component BlurBehavior() {
  <TagsInput.Root class={styles.Root} blurBehavior="add">
    <TagsInput.Context>
      component children({ context }) {
        <TagsInput.Label class={styles.Label}>{'Frameworks'}</TagsInput.Label>
        <TagsInput.Control class={styles.Control}>
          for (const value of @context.value; index i; key value) {
            <TagsInput.Item class={styles.Item} index={i} {value}>
              <TagsInput.ItemPreview class={styles.ItemPreview}>
                <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                  <X />
                </TagsInput.ItemDeleteTrigger>
              </TagsInput.ItemPreview>
              <TagsInput.ItemInput class={styles.ItemInput} />
            </TagsInput.Item>
          }
          <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
          <TagsInput.ClearTrigger class={styles.ClearTrigger}>
            <X />
          </TagsInput.ClearTrigger>
        </TagsInput.Control>
      }
    </TagsInput.Context>
    <TagsInput.HiddenInput />
  </TagsInput.Root>
}

```

### 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

**Example: paste-behavior**

```ripple
import { TagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import styles from 'styles/tags-input.module.css';

export component PasteBehavior() {
  <TagsInput.Root class={styles.Root} addOnPaste delimiter=",">
    <TagsInput.Context>
      component children({ context }) {
        <TagsInput.Label class={styles.Label}>{'Frameworks'}</TagsInput.Label>
        <TagsInput.Control class={styles.Control}>
          for (const value of @context.value; index i; key value) {
            <TagsInput.Item class={styles.Item} index={i} {value}>
              <TagsInput.ItemPreview class={styles.ItemPreview}>
                <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                  <X />
                </TagsInput.ItemDeleteTrigger>
              </TagsInput.ItemPreview>
              <TagsInput.ItemInput class={styles.ItemInput} />
            </TagsInput.Item>
          }
          <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
          <TagsInput.ClearTrigger class={styles.ClearTrigger}>
            <X />
          </TagsInput.ClearTrigger>
        </TagsInput.Control>
      }
    </TagsInput.Context>
    <TagsInput.HiddenInput />
  </TagsInput.Root>
}

```

### Disable Editing

by default the tags can be edited by double-clicking on the tag or focusing on them and pressing

<kbd>Enter</kbd>. To disable this behavior, pass `editable={false}`

**Example: disabled-editing**

```ripple
import { TagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import styles from 'styles/tags-input.module.css';

export component DisabledEditing() {
  <TagsInput.Root class={styles.Root} editable={false}>
    <TagsInput.Context>
      component children({ context }) {
        <TagsInput.Label class={styles.Label}>{'Frameworks'}</TagsInput.Label>
        <TagsInput.Control class={styles.Control}>
          for (const value of @context.value; index i; key value) {
            <TagsInput.Item class={styles.Item} index={i} {value}>
              <TagsInput.ItemPreview class={styles.ItemPreview}>
                <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                  <X />
                </TagsInput.ItemDeleteTrigger>
              </TagsInput.ItemPreview>
              <TagsInput.ItemInput class={styles.ItemInput} />
            </TagsInput.Item>
          }
          <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
          <TagsInput.ClearTrigger class={styles.ClearTrigger}>
            <X />
          </TagsInput.ClearTrigger>
        </TagsInput.Control>
      }
    </TagsInput.Context>
    <TagsInput.HiddenInput />
  </TagsInput.Root>
}

```

### Programmatic Control

Use the `useTagsInput` hook with `RootProvider` to access the component's API methods like `addValue()`, `setValue()`,
and `clearValue()` for full programmatic control.

**Example: programmatic-control**

```ripple
import { TagsInput, useTagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import styles from 'styles/tags-input.module.css';
import button from 'styles/button.module.css';

export component ProgrammaticControl() {
  const tagsInput = useTagsInput();

  <div class="stack">
    <div style={{ display: 'flex', gap: '8px' }}>
      <button class={button.Root} type="button" onClick={() => @tagsInput.addValue('React')}>
        {'Add React'}
      </button>
      <button class={button.Root} type="button" onClick={() => @tagsInput.addValue('Solid')}>
        {'Add Solid'}
      </button>
      <button
        class={button.Root}
        type="button"
        onClick={() => @tagsInput.setValue(['Vue', 'Svelte'])}
      >
        {'Set to Vue & Svelte'}
      </button>
      <button class={button.Root} type="button" onClick={() => @tagsInput.clearValue()}>
        {'Clear All'}
      </button>
    </div>

    <TagsInput.RootProvider class={styles.Root} value={tagsInput}>
      <TagsInput.Context>
        component children({ context }) {
          <TagsInput.Label class={styles.Label}>{'Frameworks'}</TagsInput.Label>
          <TagsInput.Control class={styles.Control}>
            for (const value of @context.value; index i; key value) {
              <TagsInput.Item class={styles.Item} index={i} {value}>
                <TagsInput.ItemPreview class={styles.ItemPreview}>
                  <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                  <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                    <X />
                  </TagsInput.ItemDeleteTrigger>
                </TagsInput.ItemPreview>
                <TagsInput.ItemInput class={styles.ItemInput} />
              </TagsInput.Item>
            }
            <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
            <TagsInput.ClearTrigger class={styles.ClearTrigger}>
              <X />
            </TagsInput.ClearTrigger>
          </TagsInput.Control>
        }
      </TagsInput.Context>
      <TagsInput.HiddenInput />
    </TagsInput.RootProvider>
  </div>
}

```

### Combobox

Combine TagsInput with Combobox to create an autocomplete tags input. This pattern uses shared IDs between both
components and the `asChild` prop to compose the inputs together.

**Example: with-combobox**

```ripple
import { Combobox, useCombobox, useListCollection } from 'ark-ripple/combobox';
import { useFilter } from 'ark-ripple/locale';
import { Portal } from 'ark-ripple/portal';
import { TagsInput, useTagsInput } from 'ark-ripple/tags-input';
import { Check, X } from 'lucide-ripple';
import combobox from 'styles/combobox.module.css';
import styles from 'styles/tags-input.module.css';

export component WithCombobox() {
  const filterApi = useFilter({ sensitivity: 'base' });

  const { collection, filter } = useListCollection(
    {
      initialItems: [
        'React',
        'Solid',
        'Vue',
        'Svelte',
        'Angular',
        'Preact',
        'Next.js',
        'Astro',
        'Nuxt',
      ],
      filter: @filterApi.contains,
    },
  );

  const sharedId = 'tags-combobox-1';

  const tagsInput = useTagsInput(
    {
      ids: { input: `input_${sharedId}`, control: `control_${sharedId}` },
    },
  );

  const comboboxApi = useCombobox(
    {
      ids: { input: `input_${sharedId}`, control: `control_${sharedId}` },
      collection,
      onInputValueChange(details) {
        filter(details.inputValue);
      },
      value: [],
      allowCustomValue: true,
      onValueChange: (details) => {
        if (details.value[0]) {
          @tagsInput.addValue(details.value[0]);
        }
      },
      selectionBehavior: 'clear',
    },
  );

  <Combobox.RootProvider value={comboboxApi}>
    <TagsInput.RootProvider class={styles.Root} value={tagsInput}>
      <TagsInput.Label class={styles.Label}>{'Frameworks'}</TagsInput.Label>
      <TagsInput.Control class={styles.Control}>
        for (const value of @tagsInput.value; index i; key value) {
          <TagsInput.Item class={styles.Item} index={i} {value}>
            <TagsInput.ItemPreview class={styles.ItemPreview}>
              <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
              <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                <X />
              </TagsInput.ItemDeleteTrigger>
            </TagsInput.ItemPreview>
            <TagsInput.ItemInput class={styles.ItemInput} />
          </TagsInput.Item>
        }
        <Combobox.Input>
          component asChild({ propsFn }) {
            <TagsInput.Input {...propsFn({ placeholder: 'Add Framework', class: styles.Input })} />
          }
        </Combobox.Input>
        <TagsInput.ClearTrigger class={styles.ClearTrigger}>
          <X />
        </TagsInput.ClearTrigger>
      </TagsInput.Control>
      <TagsInput.HiddenInput />
    </TagsInput.RootProvider>

    <Portal>
      <Combobox.Positioner>
        <Combobox.Content class={combobox.Content}>
          <Combobox.Empty class={combobox.Item}>{'No frameworks found'}</Combobox.Empty>
          for (const item of @collection.items; key item) {
            <Combobox.Item class={combobox.Item} {item}>
              <Combobox.ItemText class={combobox.ItemText}>{item}</Combobox.ItemText>
              <Combobox.ItemIndicator class={combobox.ItemIndicator}>
                <Check />
              </Combobox.ItemIndicator>
            </Combobox.Item>
          }
        </Combobox.Content>
      </Combobox.Positioner>
    </Portal>
  </Combobox.RootProvider>
}

```

## Guides

### Navigation

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 <kbd>Enter</kbd> or double-clicking on the tag will put it in edit mode, allowing the user change its value
  and press <kbd>Enter</kbd> to commit the changes.
- Pressing <kbd>Delete</kbd> or <kbd>Backspace</kbd> will delete the tag that has _visual_ focus.

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `addOnPaste` | `boolean` | No | Whether to add a tag when you paste values into the tag input |
| `allowOverflow` | `boolean` | No | Whether to allow tags to exceed max. In this case,
we'll attach `data-invalid` to the root |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `autoFocus` | `boolean` | No | Whether the input should be auto-focused |
| `blurBehavior` | `'clear' | 'add'` | No | The behavior of the tags input when the input is blurred
- `"add"`: add the input value as a new tag
- `"clear"`: clear the input value |
| `defaultInputValue` | `string` | No | The initial tag input value when rendered.
Use when you don't need to control the tag input value. |
| `defaultValue` | `string[]` | No | The initial tag value when rendered.
Use when you don't need to control the tag value. |
| `delimiter` | `string | RegExp` | No | The character that serves has:
- event key to trigger the addition of a new tag
- character used to split tags when pasting into the input |
| `disabled` | `boolean` | No | Whether the tags input should be disabled |
| `editable` | `boolean` | No | Whether a tag can be edited after creation, by pressing `Enter` or double clicking. |
| `form` | `string` | No | The associate form of the underlying input element. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{
  root: string
  input: string
  hiddenInput: string
  clearBtn: string
  label: string
  control: string
  item: (opts: ItemProps) => string
  itemDeleteTrigger: (opts: ItemProps) => string
  itemInput: (opts: ItemProps) => string
}>` | No | The ids of the elements in the tags input. Useful for composition. |
| `inputValue` | `string` | No | The controlled tag input's value |
| `invalid` | `boolean` | No | Whether the tags input is invalid |
| `max` | `number` | No | The max number of tags |
| `maxLength` | `number` | No | The max length of the input. |
| `name` | `string` | No | The name attribute for the input. Useful for form submissions |
| `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component |
| `onHighlightChange` | `(details: HighlightChangeDetails) => void` | No | Callback fired when a tag is highlighted by pointer or keyboard navigation |
| `onInputValueChange` | `(details: InputValueChangeDetails) => void` | No | Callback fired when the input value is updated |
| `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component |
| `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | Callback fired when the tag values is updated |
| `onValueInvalid` | `(details: ValidityChangeDetails) => void` | No | Callback fired when the max tag count is reached or the `validateTag` function returns `false` |
| `placeholder` | `string` | No | The placeholder text for the input |
| `readOnly` | `boolean` | No | Whether the tags input should be read-only |
| `required` | `boolean` | No | Whether the tags input is required |
| `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states |
| `validate` | `(details: ValidateArgs) => boolean` | No | Returns a boolean that determines whether a tag can be added.
Useful for preventing duplicates or invalid tag values. |
| `value` | `string[]` | No | The controlled tag value |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | root |
| `[data-invalid]` | Present when invalid |
| `[data-readonly]` | Present when read-only |
| `[data-disabled]` | Present when disabled |
| `[data-focus]` | Present when focused |
| `[data-empty]` | Present when the content is empty |


**ClearTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ClearTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | clear-trigger |
| `[data-readonly]` | Present when read-only |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | control |
| `[data-disabled]` | Present when disabled |
| `[data-readonly]` | Present when read-only |
| `[data-invalid]` | Present when invalid |
| `[data-focus]` | Present when focused |


**HiddenInput Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Input Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Input Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | input |
| `[data-invalid]` | Present when invalid |
| `[data-readonly]` | Present when read-only |
| `[data-empty]` | Present when the content is empty |


**ItemDeleteTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemDeleteTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | item-delete-trigger |
| `[data-disabled]` | Present when disabled |
| `[data-highlighted]` | Present when highlighted |


**ItemInput Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemPreview Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemPreview Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | item-preview |
| `[data-value]` | The value of the item |
| `[data-disabled]` | Present when disabled |
| `[data-highlighted]` | Present when highlighted |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `string | number` | Yes |  |
| `value` | `string` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `disabled` | `boolean` | No |  |


**Item Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | item |
| `[data-value]` | The value of the item |
| `[data-disabled]` | Present when disabled |


**ItemText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemText Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | item-text |
| `[data-disabled]` | Present when disabled |
| `[data-highlighted]` | Present when highlighted |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | label |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]` | Present when invalid |
| `[data-readonly]` | Present when read-only |
| `[data-required]` | Present when required |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseTagsInputReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `empty` | `boolean` | Whether the tags are empty |
| `inputValue` | `string` | The value of the tags entry input. |
| `value` | `string[]` | The value of the tags as an array of strings. |
| `valueAsString` | `string` | The value of the tags as a string. |
| `count` | `number` | The number of the tags. |
| `atMax` | `boolean` | Whether the tags have reached the max limit. |
| `setValue` | `(value: string[]) => void` | Function to set the value of the tags. |
| `clearValue` | `(id?: string) => void` | Function to clear the value of the tags. |
| `addValue` | `(value: string) => void` | Function to add a tag to the tags. |
| `setValueAtIndex` | `(index: number, value: string) => void` | Function to set the value of a tag at the given index. |
| `setInputValue` | `(value: string) => void` | Function to set the value of the tags entry input. |
| `clearInputValue` | `VoidFunction` | Function to clear the value of the tags entry input. |
| `focus` | `VoidFunction` | Function to focus the tags entry input. |
| `getItemState` | `(props: ItemProps) => ItemState` | Returns the state of a tag |


## 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: <span>When a tag item has visual focus, it puts the tag in edit mode.<br />When the input has focus, it adds the value to the list of tags</span>

**`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 



## Anatomy



```tsx
<Timer.Root>
  <Timer.Area>
    <Timer.Item />
    <Timer.Separator />
  </Timer.Area>
  <Timer.Control>
    <Timer.ActionTrigger />
  </Timer.Control>
</Timer.Root>
```

## Examples

**Example: basic**

```ripple
import { Timer } from 'ark-ripple/timer';
import { Pause, Play } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/timer.module.css';

export component Basic() {
  <Timer.Root class="stack" targetMs={60 * 60 * 1000} startMs={40 * 60 * 1000}>
    <Timer.Area class={styles.Area}>
      <div class={styles.ItemGroup}>
        <Timer.Item class={styles.Item} type="days" />
        <span class={styles.ItemLabel}>{'days'}</span>
      </div>
      <Timer.Separator class={styles.Separator}>{':'}</Timer.Separator>
      <div class={styles.ItemGroup}>
        <Timer.Item class={styles.Item} type="hours" />
        <span class={styles.ItemLabel}>{'hours'}</span>
      </div>
      <Timer.Separator class={styles.Separator}>{':'}</Timer.Separator>
      <div class={styles.ItemGroup}>
        <Timer.Item class={styles.Item} type="minutes" />
        <span class={styles.ItemLabel}>{'minutes'}</span>
      </div>
      <Timer.Separator class={styles.Separator}>{':'}</Timer.Separator>
      <div class={styles.ItemGroup}>
        <Timer.Item class={styles.Item} type="seconds" />
        <span class={styles.ItemLabel}>{'seconds'}</span>
      </div>
    </Timer.Area>
    <Timer.Control class="hstack">
      <Timer.ActionTrigger class={button.Root} action="start">
        <Play />
        {'Play'}
      </Timer.ActionTrigger>
      <Timer.ActionTrigger class={button.Root} action="resume">
        <Play />
        {'Resume'}
      </Timer.ActionTrigger>
      <Timer.ActionTrigger class={button.Root} action="pause">
        <Pause />
        {'Pause'}
      </Timer.ActionTrigger>
    </Timer.Control>
  </Timer.Root>
}

```

### Countdown

You can create a countdown timer by setting the `countdown` prop to `true` and `startMs` to the initial time:

**Example: countdown**

```ripple
import { Timer } from 'ark-ripple/timer';
import { Pause, Play, RotateCcw } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/timer.module.css';

export component Countdown() {
  <Timer.Root class="stack" countdown startMs={5 * 60 * 1000}>
    <Timer.Area class={styles.Area}>
      <div class={styles.ItemGroup}>
        <Timer.Item class={styles.Item} type="minutes" />
        <span class={styles.ItemLabel}>{'minutes'}</span>
      </div>
      <Timer.Separator class={styles.Separator}>{':'}</Timer.Separator>
      <div class={styles.ItemGroup}>
        <Timer.Item class={styles.Item} type="seconds" />
        <span class={styles.ItemLabel}>{'seconds'}</span>
      </div>
    </Timer.Area>
    <Timer.Control class="hstack">
      <Timer.ActionTrigger class={button.Root} action="start">
        <Play />
        {'Start'}
      </Timer.ActionTrigger>
      <Timer.ActionTrigger class={button.Root} action="pause">
        <Pause />
        {'Pause'}
      </Timer.ActionTrigger>
      <Timer.ActionTrigger class={button.Root} action="reset">
        <RotateCcw />
        {'Reset'}
      </Timer.ActionTrigger>
    </Timer.Control>
  </Timer.Root>
}

```

### Interval

Use the `interval` prop to control how frequently the timer updates. This is useful for displaying milliseconds:

**Example: interval**

```ripple
import { Timer } from 'ark-ripple/timer';
import { Pause, Play, RotateCcw } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/timer.module.css';

export component Interval() {
  <Timer.Root class="stack" interval={100} targetMs={60 * 1000}>
    <Timer.Area class={styles.Area}>
      <div class={styles.ItemGroup}>
        <Timer.Item class={styles.Item} type="seconds" />
        <span class={styles.ItemLabel}>{'seconds'}</span>
      </div>
      <Timer.Separator class={styles.Separator}>{'.'}</Timer.Separator>
      <div class={styles.ItemGroup}>
        <Timer.Item class={styles.Item} type="milliseconds" />
        <span class={styles.ItemLabel}>{'ms'}</span>
      </div>
    </Timer.Area>
    <Timer.Control class="hstack">
      <Timer.ActionTrigger class={button.Root} action="start">
        <Play />
        {'Start'}
      </Timer.ActionTrigger>
      <Timer.ActionTrigger class={button.Root} action="pause">
        <Pause />
        {'Pause'}
      </Timer.ActionTrigger>
      <Timer.ActionTrigger class={button.Root} action="reset">
        <RotateCcw />
        {'Reset'}
      </Timer.ActionTrigger>
    </Timer.Control>
  </Timer.Root>
}

```

### 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.

**Example: events**

```ripple
import { Timer } from 'ark-ripple/timer';
import { Play, RotateCcw } from 'lucide-ripple';
import { track } from 'ripple';
import button from 'styles/button.module.css';
import styles from 'styles/timer.module.css';

export component Events() {
  let ticks = track(0);

  <Timer.Root
    class="stack"
    targetMs={60 * 1000}
    onComplete={() => {
      console.log('Timer completed');
    }}
    onTick={() => {
      @ticks = @ticks + 1;
    }}
  >
    <Timer.Area class={styles.Area}>
      <div class={styles.ItemGroup}>
        <Timer.Item class={styles.Item} type="minutes" />
        <span class={styles.ItemLabel}>{'minutes'}</span>
      </div>
      <Timer.Separator class={styles.Separator}>{':'}</Timer.Separator>
      <div class={styles.ItemGroup}>
        <Timer.Item class={styles.Item} type="seconds" />
        <span class={styles.ItemLabel}>{'seconds'}</span>
      </div>
    </Timer.Area>

    <Timer.Control class="hstack">
      <Timer.ActionTrigger class={button.Root} action="start">
        <Play />
        {'Start'}
      </Timer.ActionTrigger>
      <Timer.ActionTrigger class={button.Root} action="reset">
        <RotateCcw />
        {'Reset'}
      </Timer.ActionTrigger>
    </Timer.Control>

    <output>
      {'Ticks: '}
      {@ticks}
    </output>
  </Timer.Root>
}

```

### Pomodoro

Here's an example of building a pomodoro timer that alternates between work and break sessions:

**Example: pomodoro**

```ripple
import { Timer } from 'ark-ripple/timer';
import { Pause, Play, RotateCcw } from 'lucide-ripple';
import { track } from 'ripple';
import button from 'styles/button.module.css';
import styles from 'styles/timer.module.css';

export component Pomodoro() {
  let isWorking = track(true);
  let cycles = track(0);

  const handleComplete = () => {
    @isWorking = !@isWorking;
    if (!@isWorking) {
      @cycles = @cycles + 1;
    }
  };

  <Timer.Root
    class="stack"
    startMs={@isWorking ? 25 * 60 * 1000 : 5 * 60 * 1000}
    countdown
    onComplete={handleComplete}
  >
    <h2>{@isWorking ? 'Work Session' : 'Break Session'}</h2>

    <Timer.Area class={styles.Area}>
      <div class={styles.ItemGroup}>
        <Timer.Item class={styles.Item} type="minutes" />
        <span class={styles.ItemLabel}>{'minutes'}</span>
      </div>
      <Timer.Separator class={styles.Separator}>{':'}</Timer.Separator>
      <div class={styles.ItemGroup}>
        <Timer.Item class={styles.Item} type="seconds" />
        <span class={styles.ItemLabel}>{'seconds'}</span>
      </div>
    </Timer.Area>

    <Timer.Control class="hstack">
      <Timer.ActionTrigger class={button.Root} action="start">
        <Play />
        {'Start'}
      </Timer.ActionTrigger>
      <Timer.ActionTrigger class={button.Root} action="pause">
        <Pause />
        {'Pause'}
      </Timer.ActionTrigger>
      <Timer.ActionTrigger class={button.Root} action="reset">
        <RotateCcw />
        {'Reset'}
      </Timer.ActionTrigger>
    </Timer.Control>

    <output>
      {'Completed cycles: '}
      {@cycles}
    </output>
  </Timer.Root>
}

```

### Root Provider

An alternative way to control the timer is to use the `RootProvider` component and the `useTimer` hook. This way you can
access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { Timer, useTimer } from 'ark-ripple/timer';
import { Pause, Play, RotateCcw } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/timer.module.css';

export component RootProvider() {
  const timer = useTimer({ targetMs: 60 * 60 * 1000 });

  <div class="stack">
    <output>
      {'timer: '}
      {JSON.stringify(@timer.time)}
    </output>
    <Timer.RootProvider class={styles.Root} value={timer}>
      <Timer.Area class={styles.Area}>
        <div class={styles.ItemGroup}>
          <Timer.Item class={styles.Item} type="hours" />
          <span class={styles.ItemLabel}>{'hours'}</span>
        </div>
        <Timer.Separator class={styles.Separator}>{':'}</Timer.Separator>
        <div class={styles.ItemGroup}>
          <Timer.Item class={styles.Item} type="minutes" />
          <span class={styles.ItemLabel}>{'minutes'}</span>
        </div>
        <Timer.Separator class={styles.Separator}>{':'}</Timer.Separator>
        <div class={styles.ItemGroup}>
          <Timer.Item class={styles.Item} type="seconds" />
          <span class={styles.ItemLabel}>{'seconds'}</span>
        </div>
      </Timer.Area>
      <Timer.Control class="hstack">
        <Timer.ActionTrigger class={button.Root} action="start">
          <Play />
          {'Start'}
        </Timer.ActionTrigger>
        <Timer.ActionTrigger class={button.Root} action="resume">
          <Play />
          {'Resume'}
        </Timer.ActionTrigger>
        <Timer.ActionTrigger class={button.Root} action="pause">
          <Pause />
          {'Pause'}
        </Timer.ActionTrigger>
        <Timer.ActionTrigger class={button.Root} action="reset">
          <RotateCcw />
          {'Reset'}
        </Timer.ActionTrigger>
      </Timer.Control>
    </Timer.RootProvider>
  </div>
}

```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `autoStart` | `boolean` | No | Whether the timer should start automatically |
| `countdown` | `boolean` | No | Whether the timer should countdown, decrementing the timer on each tick. |
| `ids` | `Partial<{ root: string; area: string }>` | No | The ids of the timer parts |
| `interval` | `number` | No | The interval in milliseconds to update the timer count. |
| `onComplete` | `() => void` | No | Function invoked when the timer is completed |
| `onTick` | `(details: TickDetails) => void` | No | Function invoked when the timer ticks |
| `startMs` | `number` | No | The total duration of the timer in milliseconds. |
| `targetMs` | `number` | No | The minimum count of the timer in milliseconds. |


**ActionTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `action` | `TimerAction` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Area Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `type` | `keyof Time<number>` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Item Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | timer |
| `[data-part]` | item |
| `[data-type]` | The type of the item |


**Item CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--value` | The current value |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseTimerReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Separator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `running` | `boolean` | Whether the timer is running. |
| `paused` | `boolean` | Whether the timer is paused. |
| `time` | `Time<number>` | The formatted timer count value. |
| `formattedTime` | `Time<string>` | The formatted time parts of the timer count. |
| `start` | `VoidFunction` | Function to start the timer. |
| `pause` | `VoidFunction` | Function to pause the timer. |
| `resume` | `VoidFunction` | Function to resume the timer. |
| `reset` | `VoidFunction` | Function to reset the timer. |
| `restart` | `VoidFunction` | Function to restart the timer. |
| `progressPercent` | `number` | The progress percentage of the timer. |



# Toast 



## Anatomy



```tsx
const toaster = createToaster({ placement: 'bottom-end' })

<Toaster toaster={toaster}>
  {(toast) => (
    <Toast.Root>
      <Toast.Title />
      <Toast.Description />
      <Toast.ActionTrigger />
      <Toast.CloseTrigger />
    </Toast.Root>
  )}
</Toaster>
```

## 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.

**Example: basic**

```ripple
import { Toast, Toaster, createToaster } from 'ark-ripple/toast';
import { Portal } from 'ark-ripple/portal';
import { X } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/toast.module.css';

const toaster = createToaster(
  {
    placement: 'bottom-end',
    overlap: true,
    gap: 24,
  },
);

export component Basic() {
  <div>
    <button
      type="button"
      class={button.Root}
      onClick={() => {
        toaster.create(
          {
            title: 'Scheduled for tomorrow',
            description: 'Your meeting has been scheduled for tomorrow at 10am.',
            type: 'info',
          },
        );
      }}
    >
      {'Schedule meeting'}
    </button>
    <Portal>
      <Toaster {toaster}>
        component children({ toast }) {
          <Toast.Root class={styles.Root}>
            <Toast.Title class={styles.Title}>{@toast.title}</Toast.Title>
            <Toast.Description class={styles.Description}>{@toast.description}</Toast.Description>
            <Toast.CloseTrigger class={styles.CloseTrigger}>
              <X />
            </Toast.CloseTrigger>
          </Toast.Root>
        }
      </Toaster>
    </Portal>
  </div>
}

```

### Types

You can create different types of toasts (`success`, `error`, `warning`, `info`) with appropriate styling. For example,
to create a success toast, you can do:

```ts
toaster.success({
  title: 'Success!',
  description: 'Your changes have been saved.',
})
```

**Example: types**

```ripple
import { Toast, Toaster, createToaster } from 'ark-ripple/toast';
import { Portal } from 'ark-ripple/portal';
import { CircleAlert, TriangleAlert, CircleCheck, Info, X } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/toast.module.css';

const toaster = createToaster(
  {
    overlap: true,
    placement: 'bottom-end',
    gap: 16,
  },
);

const iconMap = {
  success: CircleCheck,
  error: CircleAlert,
  warning: TriangleAlert,
  info: Info,
};

export component Types() {
  <div>
    <div style={{ display: 'flex', gap: '12px', flexWrap: 'wrap' }}>
      <button
        type="button"
        class={button.Root}
        onClick={() => {
          toaster.success(
            { title: 'Changes saved', description: 'Your profile has been updated successfully.' },
          );
        }}
      >
        {'Success'}
      </button>
      <button
        type="button"
        class={button.Root}
        onClick={() => {
          toaster.error(
            { title: 'Upload failed', description: 'There was an error uploading your file.' },
          );
        }}
      >
        {'Error'}
      </button>
      <button
        type="button"
        class={button.Root}
        onClick={() => {
          toaster.warning(
            { title: 'Low storage', description: 'You have less than 10% storage remaining.' },
          );
        }}
      >
        {'Warning'}
      </button>
      <button
        type="button"
        class={button.Root}
        onClick={() => {
          toaster.info(
            {
              title: 'Update available',
              description: 'A new version of the app is ready to install.',
            },
          );
        }}
      >
        {'Info'}
      </button>
    </div>

    <Portal>
      <Toaster {toaster}>
        component children({ toast }) {
          const ToastIcon = @toast.type ? iconMap[@toast.type as keyof typeof iconMap] : undefined;
          <Toast.Root class={styles.Root}>
            <Toast.Title class={styles.Title}>
              if (ToastIcon) {
                <ToastIcon class={styles.Indicator} />
              }
              {@toast.title}
            </Toast.Title>
            <Toast.Description class={styles.Description}>{@toast.description}</Toast.Description>
            <Toast.CloseTrigger class={styles.CloseTrigger}>
              <X />
            </Toast.CloseTrigger>
          </Toast.Root>
        }
      </Toaster>
    </Portal>
  </div>
}

```

### Promise

You can use `toaster.promise()` to automatically handle the different states of an asynchronous operation. It provides
options for the `success`, `error`, and `loading` states of the promise and will automatically update the toast when the
promise resolves or rejects.

**Example: promise-toast**

```ripple
import { Toast, Toaster, createToaster } from 'ark-ripple/toast';
import { Portal } from 'ark-ripple/portal';
import { X, Loader, CircleCheck, CircleAlert } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/toast.module.css';

const toaster = createToaster(
  {
    overlap: true,
    placement: 'bottom-end',
    gap: 16,
  },
);

const uploadFile = () => {
  return new Promise<void>((resolve, reject) => {
    setTimeout(() => {
      Math.random() > 0.5 ? resolve() : reject(new Error('Upload failed'));
    }, 2000);
  });
};

export component PromiseToast() {
  const handleUpload = async () => {
    toaster.promise(uploadFile, {
      loading: {
        title: 'Uploading file...',
        description: 'Please wait while we upload your document.',
      },
      success: {
        title: 'Upload complete',
        description: 'Your file has been uploaded successfully.',
      },
      error: {
        title: 'Upload failed',
        description: 'Could not upload the file. Please try again.',
      },
    });
  };

  <div>
    <button type="button" class={button.Root} onClick={handleUpload}>{'Upload file'}</button>

    <Portal>
      <Toaster {toaster}>
        component children({ toast }) {
          <Toast.Root class={styles.Root}>
            <Toast.Title class={styles.Title}>
              if (@toast.type === 'loading') {
                <Loader class={styles.Indicator} data-type="loading" />
              } else if (@toast.type === 'success') {
                <CircleCheck class={styles.Indicator} />
              } else if (@toast.type === 'error') {
                <CircleAlert class={styles.Indicator} />
              }
              {@toast.title}
            </Toast.Title>
            <Toast.Description class={styles.Description}>{@toast.description}</Toast.Description>
            <Toast.CloseTrigger class={styles.CloseTrigger}>
              <X />
            </Toast.CloseTrigger>
          </Toast.Root>
        }
      </Toaster>
    </Portal>
  </div>
}

```

### Update

To update a toast, use the `toast.update` method.

**Example: update**

```ripple
import { track } from 'ripple';
import { Toast, Toaster, createToaster } from 'ark-ripple/toast';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import styles from 'styles/toast.module.css';

const toaster = createToaster(
  {
    placement: 'bottom-end',
    overlap: true,
    gap: 24,
  },
);

export component Update() {
  let id = track<string | undefined>(undefined);

  const createToast = () => {
    @id = toaster.create(
      {
        title: 'Sending message...',
        description: 'Please wait while we deliver your message.',
        type: 'loading',
      },
    );
  };

  const updateToast = () => {
    if (!@id) {
      return;
    }
    toaster.update(@id, {
      title: 'Message sent',
      description: 'Your message has been delivered successfully.',
      type: 'success',
    });
  };

  <div class="hstack">
    <button type="button" class={button.Root} onClick={createToast}>{'Send message'}</button>
    <button type="button" class={button.Root} onClick={updateToast}>{'Mark as sent'}</button>
    <Portal>
      <Toaster {toaster}>
        component children({ toast }) {
          <Toast.Root class={styles.Root}>
            <Toast.Title class={styles.Title}>{@toast.title}</Toast.Title>
            <Toast.Description class={styles.Description}>{@toast.description}</Toast.Description>
          </Toast.Root>
        }
      </Toaster>
    </Portal>
  </div>
}

```

### Action

To add an action to a toast, use the `toast.action` property.

**Example: action**

```ripple
import { Toast, Toaster, createToaster } from 'ark-ripple/toast';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import styles from 'styles/toast.module.css';

const toaster = createToaster(
  {
    placement: 'bottom-end',
    gap: 24,
  },
);

export component Action() {
  <div>
    <button
      type="button"
      class={button.Root}
      onClick={() => {
        toaster.create(
          {
            title: 'Event has been created',
            description: 'We have sent you an email with the event details.',
            type: 'info',
            action: {
              label: 'Undo',
              onClick: () => {
                console.log('Undo');
              },
            },
          },
        );
      }}
    >
      {'Create event'}
    </button>
    <Portal>
      <Toaster {toaster}>
        component children({ toast }) {
          <Toast.Root class={styles.Root}>
            <Toast.Title class={styles.Title}>{@toast.title}</Toast.Title>
            <Toast.Description class={styles.Description}>{@toast.description}</Toast.Description>
            if (@toast.action) {
              <Toast.ActionTrigger class={styles.ActionTrigger}>
                {@toast.action?.label}
              </Toast.ActionTrigger>
            }
          </Toast.Root>
        }
      </Toaster>
    </Portal>
  </div>
}

```

### Duration

You can control how long a toast stays visible by setting a custom `duration` in milliseconds, or use `Infinity` to keep
it visible until manually dismissed.

**Example: duration**

```ripple
import { Toast, Toaster, createToaster } from 'ark-ripple/toast';
import { Portal } from 'ark-ripple/portal';
import { X, Clock } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/toast.module.css';

const toaster = createToaster(
  {
    overlap: true,
    placement: 'bottom-end',
    gap: 16,
  },
);

const durations = [
  { label: '1s', value: 1000 },
  { label: '3s', value: 3000 },
  { label: '5s', value: 5000 },
  { label: '∞', value: Infinity },
];

export component Duration() {
  <div>
    <div style={{ display: 'flex', flexWrap: 'wrap', gap: '8px' }}>
      for (const duration of durations; key duration.label) {
        <button
          type="button"
          class={button.Root}
          onClick={() => {
            toaster.create(
              {
                title: 'Reminder set',
                description: `This notification will ${
                  duration.value === Infinity
                    ? 'stay until dismissed'
                    : `disappear in ${duration.label}`
                }.`,
                type: 'info',
                duration: duration.value,
              },
            );
          }}
        >
          {duration.label}
        </button>
      }
    </div>

    <Portal>
      <Toaster {toaster}>
        component children({ toast }) {
          <Toast.Root class={styles.Root}>
            <Toast.Title class={styles.Title}>
              <Clock class={styles.Indicator} />
              {@toast.title}
            </Toast.Title>
            <Toast.Description class={styles.Description}>{@toast.description}</Toast.Description>
            <Toast.CloseTrigger class={styles.CloseTrigger}>
              <X />
            </Toast.CloseTrigger>
          </Toast.Root>
        }
      </Toaster>
    </Portal>
  </div>
}

```

### Max Visible

Set the `max` prop on the `createToaster` function to define the maximum number of toasts that can be rendered at any
one time. Any extra toasts will be queued and rendered when a toast has been dismissed.

**Example: max-toasts**

```ripple
import { Toast, Toaster, createToaster } from 'ark-ripple/toast';
import { Portal } from 'ark-ripple/portal';
import { X, Info } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/toast.module.css';

const toaster = createToaster(
  {
    max: 3,
    overlap: true,
    placement: 'bottom-end',
    gap: 16,
  },
);

export component MaxToasts() {
  <div>
    <div style={{ display: 'flex', flexWrap: 'wrap', gap: '8px' }}>
      <button
        type="button"
        class={button.Root}
        onClick={() => {
          toaster.create(
            {
              title: 'New notification',
              description: 'You have a new message in your inbox.',
              type: 'info',
            },
          );
        }}
      >
        {'Add notification'}
      </button>
      <button
        type="button"
        class={button.Root}
        onClick={() => {
          const messages = [
            'John liked your post',
            'Sarah commented on your photo',
            'New follower: @designpro',
            'Your post was shared 10 times',
            'Meeting reminder in 15 minutes',
          ];
          messages.forEach((msg) => {
            toaster.create(
              {
                title: 'Notification',
                description: msg,
                type: 'info',
              },
            );
          });
        }}
      >
        {'Add 5 notifications'}
      </button>
    </div>

    <Portal>
      <Toaster {toaster}>
        component children({ toast }) {
          <Toast.Root class={styles.Root}>
            <Info class={styles.Indicator} />
            <div style={{ flex: 1 }}>
              <Toast.Title class={styles.Title}>{@toast.title}</Toast.Title>
              <Toast.Description class={styles.Description}>{@toast.description}</Toast.Description>
            </div>
            <Toast.CloseTrigger class={styles.CloseTrigger}>
              <X />
            </Toast.CloseTrigger>
          </Toast.Root>
        }
      </Toaster>
    </Portal>
  </div>
}

```

### Placement

Configure where toasts appear on the screen using the `placement` option in `createToaster`. Options include
`top-start`, `top-end`, `bottom-start`, `bottom-end`, and more.

**Example: placement**

```ripple
import { Toast, Toaster, createToaster } from 'ark-ripple/toast';
import { Portal } from 'ark-ripple/portal';
import { X } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/toast.module.css';

const toaster = createToaster(
  {
    placement: 'top-end',
    overlap: true,
    gap: 16,
  },
);

export component Placement() {
  <div>
    <button
      type="button"
      class={button.Root}
      onClick={() => {
        toaster.create(
          {
            title: 'Notification',
            description: 'This toast appears at the top-right corner.',
            type: 'info',
          },
        );
      }}
    >
      {'Show toast (top-end)'}
    </button>
    <Portal>
      <Toaster {toaster}>
        component children({ toast }) {
          <Toast.Root class={styles.Root}>
            <Toast.Title class={styles.Title}>{@toast.title}</Toast.Title>
            <Toast.Description class={styles.Description}>{@toast.description}</Toast.Description>
            <Toast.CloseTrigger class={styles.CloseTrigger}>
              <X />
            </Toast.CloseTrigger>
          </Toast.Root>
        }
      </Toaster>
    </Portal>
  </div>
}

```

## Guides

### Toast in Effects

When creating a toast inside effect (like `effect`, or event handlers that trigger during
render), you may encounter a "flushSync" warning. To avoid this, wrap the toast call in `queueMicrotask`:

```tsx
import { effect } from 'ripple'

export component EffectToast() {
  effect(() => {
    // ❌ This may cause flushSync warnings
    // toaster.create({ title: 'Effect triggered!' })

    // ✅ Wrap in queueMicrotask to avoid warnings
    queueMicrotask(() => {
      toaster.create({
        title: 'Effect triggered!',
        description: 'This toast was called safely from an effect',
        type: 'success',
      })
    })
  })

  <div>Component content</div>
}
```

This ensures the toast creation is deferred until after the current execution context, preventing React's concurrent
rendering warnings.

### Styling

There's a minimal styling required for the toast to work correctly.

#### Toast root

The toast root will be assigned these css properties at runtime:

- `--x` - The x position
- `--y` - The y position
- `--scale` - The scale
- `--z-index` - The z-index
- `--height` - The height
- `--opacity` - The opacity
- `--gap` - The gap between toasts

```css
[data-scope='toast'][data-part='root'] {
  translate: var(--x) var(--y);
  scale: var(--scale);
  z-index: var(--z-index);
  height: var(--height);
  opacity: var(--opacity);
  will-change: translate, opacity, scale;
  transition:
    translate 400ms,
    scale 400ms,
    opacity 400ms,
    height 400ms,
    box-shadow 200ms;
  transition-timing-function: cubic-bezier(0.21, 1.02, 0.73, 1);

  &[data-state='closed'] {
    transition:
      translate 400ms,
      scale 400ms,
      opacity 200ms;
    transition-timing-function: cubic-bezier(0.06, 0.71, 0.55, 1);
  }
}
```

#### Styling based on type

You can also style based on the `data-type` attribute.

```css
[data-scope='toast'][data-part='root'] {
  &[data-type='error'] {
    background: red;
    color: white;
  }

  &[data-type='info'] {
    background: blue;
    color: white;
  }

  &[data-type='warning'] {
    background: orange;
  }

  &[data-type='success'] {
    background: green;
    color: white;
  }
}
```

#### Mobile considerations

A very common use case is to adjust the toast width on mobile so it spans the full width of the screen.

```css
@media (max-width: 640px) {
  [data-scope='toast'][data-part='group'] {
    width: 100%;
  }

  [data-scope='toast'][data-part='root'] {
    inset-inline: 0;
    width: calc(100% - var(--gap) * 2);
  }
}
```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | toast |
| `[data-part]` | root |
| `[data-state]` | "open" | "closed" |
| `[data-type]` | The type of the item |
| `[data-placement]` | The placement of the toast |
| `[data-align]` |  |
| `[data-side]` |  |
| `[data-mounted]` | Present when mounted |
| `[data-paused]` | Present when paused |
| `[data-first]` |  |
| `[data-sibling]` |  |
| `[data-stack]` |  |
| `[data-overlap]` | Present when overlapping |


**ActionTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**CloseTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Description Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Store Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `duration` | `number` | No | The duration of the toast.
By default, it is determined by the type of the toast. |
| `gap` | `number` | No | The gap between the toasts |
| `hotkey` | `string[]` | No | The hotkey that will move focus to the toast group |
| `max` | `number` | No | The maximum number of toasts. When the number of toasts exceeds this limit, the new toasts are queued. |
| `offsets` | `string | Record<'top' | 'bottom' | 'left' | 'right', string>` | No | The offset from the safe environment edge of the viewport |
| `overlap` | `boolean` | No | Whether to overlap the toasts |
| `pauseOnPageIdle` | `boolean` | No | Whether to pause toast when the user leaves the browser tab |
| `placement` | `Placement` | No | The placement of the toast |
| `removeDelay` | `number` | No | The duration for the toast to kept alive before it is removed.
Useful for exit transitions. |


**Title Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Toaster Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `toaster` | `CreateToasterReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `dir` | `'ltr' | 'rtl'` | No | The document's text/writing direction. |
| `getRootNode` | `() => Node | ShadowRoot | Document` | No | A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron. |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `getCount` | `() => number` | The total number of toasts |
| `getToasts` | `() => ToastProps<any>[]` | The toasts |
| `subscribe` | `(callback: (toasts: Options<O>[]) => void) => VoidFunction` | Subscribe to the toast group |



# Toggle 



## Anatomy



```tsx
<Toggle.Root>
  <Toggle.Indicator />
</Toggle.Root>
```

## Examples

**Example: basic**

```ripple
import { Toggle } from 'ark-ripple/toggle';
import { Bold } from 'lucide-ripple';
import styles from 'styles/toggle.module.css';

export component Basic() {
  <Toggle.Root class={styles.Root}>
    <Bold />
  </Toggle.Root>
}

```

### Controlled

Use the `pressed` and `onPressedChange` props to control the toggle's state.

**Example: controlled**

```ripple
import { Toggle } from 'ark-ripple/toggle';
import { Heart } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/toggle.module.css';

export component Controlled() {
  let pressed = track(false);

  <Toggle.Root
    class={styles.Root}
    {pressed}
    onPressedChange={(value) => {
      @pressed = value;
    }}
  >
    <Toggle.Indicator
      class={styles.Indicator}
      fallback={component() {
        <Heart />
      }}
    >
      <Heart fill="currentColor" />
    </Toggle.Indicator>
  </Toggle.Root>
}

```

### Disabled

Use the `disabled` prop to disable the toggle.

**Example: disabled**

```ripple
import { Toggle } from 'ark-ripple/toggle';
import { Bold } from 'lucide-ripple';
import styles from 'styles/toggle.module.css';

export component Disabled() {
  <Toggle.Root class={styles.Root} disabled>
    <Bold />
  </Toggle.Root>
}

```

### Indicator

Use the `Toggle.Indicator` component to render different indicators based on the state of the toggle.

**Example: indicator**

```ripple
import { Toggle } from 'ark-ripple/toggle';
import { Heart } from 'lucide-ripple';
import styles from 'styles/toggle.module.css';

export component Indicator() {
  <Toggle.Root class={styles.Root}>
    <Toggle.Indicator
      class={styles.Indicator}
      fallback={component() {
        <Heart />
      }}
    >
      <Heart fill="currentColor" />
    </Toggle.Indicator>
  </Toggle.Root>
}

```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `defaultPressed` | `boolean` | No | The default pressed state of the toggle. |
| `onPressedChange` | `(pressed: boolean) => void` | No | Event handler called when the pressed state of the toggle changes. |
| `pressed` | `boolean` | No | The pressed state of the toggle. |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | toggle |
| `[data-part]` | root |
| `[data-state]` | "on" | "off" |
| `[data-pressed]` | Present when pressed |
| `[data-disabled]` | Present when disabled |


**Indicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `fallback` | `string | number | bigint | boolean | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...>` | No | The fallback content to render when the toggle is not pressed. |


**Indicator Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | toggle |
| `[data-part]` | indicator |
| `[data-disabled]` | Present when disabled |
| `[data-pressed]` | Present when pressed |
| `[data-state]` | "on" | "off" |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `pressed` | `boolean` | Whether the toggle is pressed. |
| `disabled` | `boolean` | Whether the toggle is disabled. |
| `setPressed` | `(pressed: boolean) => void` | Sets the pressed state of the toggle. |



# Toggle Group 



## Anatomy



```tsx
<ToggleGroup.Root>
  <ToggleGroup.Item />
</ToggleGroup.Root>
```

## Examples

**Example: basic**

```ripple
import { ToggleGroup } from 'ark-ripple/toggle-group';
import { TextAlignCenter, TextAlignJustify, TextAlignStart, TextAlignEnd } from 'lucide-ripple';
import styles from 'styles/toggle-group.module.css';

export component Basic() {
  <ToggleGroup.Root defaultValue={['left']} class={styles.Root}>
    <ToggleGroup.Item value="left" class={styles.Item}>
      <TextAlignStart />
    </ToggleGroup.Item>
    <ToggleGroup.Item value="center" class={styles.Item}>
      <TextAlignCenter />
    </ToggleGroup.Item>
    <ToggleGroup.Item value="right" class={styles.Item}>
      <TextAlignEnd />
    </ToggleGroup.Item>
    <ToggleGroup.Item value="justify" class={styles.Item}>
      <TextAlignJustify />
    </ToggleGroup.Item>
  </ToggleGroup.Root>
}

```

### Controlled

Use the `value` and `onValueChange` props to control the toggle group state.

**Example: controlled**

```ripple
import { ToggleGroup } from 'ark-ripple/toggle-group';
import { TextAlignCenter, TextAlignJustify, TextAlignStart, TextAlignEnd } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/toggle-group.module.css';

export component Controlled() {
  let value = track<string[]>(['left']);

  <ToggleGroup.Root
    {value}
    onValueChange={(e) => {
      @value = e.value;
    }}
    class={styles.Root}
  >
    <ToggleGroup.Item value="left" class={styles.Item}>
      <TextAlignStart />
    </ToggleGroup.Item>
    <ToggleGroup.Item value="center" class={styles.Item}>
      <TextAlignCenter />
    </ToggleGroup.Item>
    <ToggleGroup.Item value="right" class={styles.Item}>
      <TextAlignEnd />
    </ToggleGroup.Item>
    <ToggleGroup.Item value="justify" class={styles.Item}>
      <TextAlignJustify />
    </ToggleGroup.Item>
  </ToggleGroup.Root>
}

```

### Root Provider

An alternative way to control the toggle group is to use the `RootProvider` component and the `useToggleGroup` hook.
This way you can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { ToggleGroup, useToggleGroup } from 'ark-ripple/toggle-group';
import { TextAlignCenter, TextAlignJustify, TextAlignStart, TextAlignEnd } from 'lucide-ripple';
import styles from 'styles/toggle-group.module.css';

export component RootProvider() {
  const toggleGroup = useToggleGroup({ defaultValue: ['left'] });

  <div class="stack">
    <output>
      {'Value: '}
      {@toggleGroup.value.join(', ')}
    </output>
    <ToggleGroup.RootProvider value={toggleGroup} class={styles.Root}>
      <ToggleGroup.Item value="left" class={styles.Item}>
        <TextAlignStart />
      </ToggleGroup.Item>
      <ToggleGroup.Item value="center" class={styles.Item}>
        <TextAlignCenter />
      </ToggleGroup.Item>
      <ToggleGroup.Item value="right" class={styles.Item}>
        <TextAlignEnd />
      </ToggleGroup.Item>
      <ToggleGroup.Item value="justify" class={styles.Item}>
        <TextAlignJustify />
      </ToggleGroup.Item>
    </ToggleGroup.RootProvider>
  </div>
}

```

### Multiple

Demonstrates how to enable `multiple` selection within the group.

**Example: multiple**

```ripple
import { ToggleGroup } from 'ark-ripple/toggle-group';
import { Bold, Italic, Underline } from 'lucide-ripple';
import styles from 'styles/toggle-group.module.css';

export component Multiple() {
  <ToggleGroup.Root defaultValue={['bold']} multiple class={styles.Root}>
    <ToggleGroup.Item value="bold" class={styles.Item}>
      <Bold />
    </ToggleGroup.Item>
    <ToggleGroup.Item value="italic" class={styles.Item}>
      <Italic />
    </ToggleGroup.Item>
    <ToggleGroup.Item value="underline" class={styles.Item}>
      <Underline />
    </ToggleGroup.Item>
  </ToggleGroup.Root>
}

```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `defaultValue` | `string[]` | No | The initial selected value of the toggle group when rendered.
Use when you don't need to control the selected value of the toggle group. |
| `deselectable` | `boolean` | No | Whether the toggle group allows empty selection.
**Note:** This is ignored if `multiple` is `true`. |
| `disabled` | `boolean` | No | Whether the toggle is disabled. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{ root: string; item: (value: string) => string }>` | No | The ids of the elements in the toggle. Useful for composition. |
| `loopFocus` | `boolean` | No | Whether to loop focus inside the toggle group. |
| `multiple` | `boolean` | No | Whether to allow multiple toggles to be selected. |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | Function to call when the toggle is clicked. |
| `orientation` | `Orientation` | No | The orientation of the toggle group. |
| `rovingFocus` | `boolean` | No | Whether to use roving tab index to manage focus. |
| `value` | `string[]` | No | The controlled selected value of the toggle group. |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | toggle-group |
| `[data-part]` | root |
| `[data-disabled]` | Present when disabled |
| `[data-orientation]` | The orientation of the toggle-group |
| `[data-focus]` | Present when focused |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `string` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `disabled` | `boolean` | No |  |


**Item Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | toggle-group |
| `[data-part]` | item |
| `[data-focus]` | Present when focused |
| `[data-disabled]` | Present when disabled |
| `[data-orientation]` | The orientation of the item |
| `[data-state]` | "on" | "off" |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseToggleGroupReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `value` | `string[]` | The value of the toggle group. |
| `setValue` | `(value: string[]) => void` | Sets the value of the toggle group. |
| `getItemState` | `(props: ItemProps) => ItemState` | Returns the state of the toggle item. |


## 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.


# Tooltip 



## Anatomy



```tsx
<Tooltip.Root>
  <Tooltip.Trigger />
  <Tooltip.Positioner>
    <Tooltip.Arrow>
      <Tooltip.ArrowTip />
    </Tooltip.Arrow>
    <Tooltip.Content />
  </Tooltip.Positioner>
</Tooltip.Root>
```

## Examples

**Example: basic**

```ripple
import { Tooltip } from 'ark-ripple/tooltip';
import { Portal } from 'ark-ripple/portal';
import styles from 'styles/tooltip.module.css';

export component Basic() {
  <Tooltip.Root>
    <Tooltip.Trigger class={styles.Trigger}>{'Hover Me'}</Tooltip.Trigger>
    <Portal>
      <Tooltip.Positioner>
        <Tooltip.Content class={styles.Content}>{'I am a tooltip!'}</Tooltip.Content>
      </Tooltip.Positioner>
    </Portal>
  </Tooltip.Root>
}

```

### Controlled

To create a controlled Tooltip component, manage the state of whether the tooltip is open using the `open` prop:

**Example: controlled**

```ripple
import { Tooltip } from 'ark-ripple/tooltip';
import { Portal } from 'ark-ripple/portal';
import { track } from 'ripple';
import styles from 'styles/tooltip.module.css';
import button from 'styles/button.module.css';

export component Controlled() {
  let open = track(false);

  <div class="stack">
    <button
      type="button"
      onClick={() => {
        @open = !@open;
      }}
      class={button.Root}
    >
      {'Toggle'}
    </button>
    <Tooltip.Root
      {open}
      onOpenChange={(e) => {
        @open = e.open;
      }}
    >
      <Tooltip.Trigger class={styles.Trigger}>{'Hover Me'}</Tooltip.Trigger>
      <Portal>
        <Tooltip.Positioner>
          <Tooltip.Content class={styles.Content}>{'I am a tooltip!'}</Tooltip.Content>
        </Tooltip.Positioner>
      </Portal>
    </Tooltip.Root>
  </div>
}

```

### Root Provider

An alternative way to control the tooltip is to use the `RootProvider` component and the `useTooltip` hook. This way you
can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { Tooltip, useTooltip } from 'ark-ripple/tooltip';
import { Portal } from 'ark-ripple/portal';
import styles from 'styles/tooltip.module.css';

export component RootProvider() {
  const tooltip = useTooltip();

  <output>
    {'Open: '}
    {String(@tooltip.open)}
  </output>
  <Tooltip.RootProvider value={tooltip}>
    <Tooltip.Trigger class={styles.Trigger}>{'Hover Me'}</Tooltip.Trigger>
    <Portal>
      <Tooltip.Positioner>
        <Tooltip.Content class={styles.Content}>{'I am a tooltip!'}</Tooltip.Content>
      </Tooltip.Positioner>
    </Portal>
  </Tooltip.RootProvider>
}

```

### Arrow

To display an arrow pointing to the trigger from the tooltip, use the `Tooltip.Arrow` and `Tooltip.ArrowTip` components:

**Example: arrow**

```ripple
import { Tooltip } from 'ark-ripple/tooltip';
import { Portal } from 'ark-ripple/portal';
import styles from 'styles/tooltip.module.css';

export component Arrow() {
  <Tooltip.Root>
    <Tooltip.Trigger class={styles.Trigger}>{'Hover Me'}</Tooltip.Trigger>
    <Portal>
      <Tooltip.Positioner>
        <Tooltip.Content class={styles.Content}>
          <Tooltip.Arrow class={styles.Arrow}>
            <Tooltip.ArrowTip class={styles.ArrowTip} />
          </Tooltip.Arrow>
          {'I am a tooltip!'}
        </Tooltip.Content>
      </Tooltip.Positioner>
    </Portal>
  </Tooltip.Root>
}

```

### Delay

To configure the open and close delay for the Tooltip, use the `closeDelay` and `openDelay` props:

**Example: delay**

```ripple
import { Tooltip } from 'ark-ripple/tooltip';
import { Portal } from 'ark-ripple/portal';
import styles from 'styles/tooltip.module.css';

export component Delay() {
  <Tooltip.Root closeDelay={0} openDelay={0}>
    <Tooltip.Trigger class={styles.Trigger}>{'Hover Me'}</Tooltip.Trigger>
    <Portal>
      <Tooltip.Positioner>
        <Tooltip.Content class={styles.Content}>{'I am a tooltip!'}</Tooltip.Content>
      </Tooltip.Positioner>
    </Portal>
  </Tooltip.Root>
}

```

### Positioning

To customize the position of the Tooltip relative to the trigger, use the `positioning` prop:

**Example: positioning**

```ripple
import { Tooltip } from 'ark-ripple/tooltip';
import { Portal } from 'ark-ripple/portal';
import styles from 'styles/tooltip.module.css';

export component Positioning() {
  <Tooltip.Root
    positioning={{
      placement: 'left-start',
      offset: { mainAxis: 12, crossAxis: 12 },
    }}
  >
    <Tooltip.Trigger class={styles.Trigger}>{'Hover Me'}</Tooltip.Trigger>
    <Portal>
      <Tooltip.Positioner>
        <Tooltip.Content class={styles.Content}>{'I am a tooltip!'}</Tooltip.Content>
      </Tooltip.Positioner>
    </Portal>
  </Tooltip.Root>
}

```

### Context

Access the tooltip's state and methods with `Tooltip.Context` or the `useTooltipContext` hook:

**Example: context**

```ripple
import { Tooltip } from 'ark-ripple/tooltip';
import { Portal } from 'ark-ripple/portal';
import styles from 'styles/tooltip.module.css';

export component Context() {
  <Tooltip.Root>
    <Tooltip.Trigger class={styles.Trigger}>{'Hover Me'}</Tooltip.Trigger>
    <Portal>
      <Tooltip.Positioner>
        <Tooltip.Context>
          component children({ context }) {
            <Tooltip.Content class={styles.Content}>
              {'This tooltip is open: '}
              {String(@context.open)}
            </Tooltip.Content>
          }
        </Tooltip.Context>
      </Tooltip.Positioner>
    </Portal>
  </Tooltip.Root>
}

```

### Within Fixed Containers

When rendering a tooltip inside a fixed-position container, set `positioning.strategy` to `"fixed"` to ensure proper
positioning.

**Example: within-fixed**

```ripple
import { Tooltip } from 'ark-ripple/tooltip';
import { Portal } from 'ark-ripple/portal';
import styles from 'styles/tooltip.module.css';

export component WithinFixed() {
  <div style={{ position: 'fixed', top: '40px', left: '40px', padding: '40px', background: 'red' }}>
    <Tooltip.Root positioning={{ strategy: 'fixed' }}>
      <Tooltip.Trigger class={styles.Trigger}>{'Hover Me'}</Tooltip.Trigger>
      <Portal>
        <Tooltip.Positioner>
          <Tooltip.Content class={styles.Content}>{'I am a tooltip!'}</Tooltip.Content>
        </Tooltip.Positioner>
      </Portal>
    </Tooltip.Root>
  </div>
}

```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `aria-label` | `string` | No | Custom label for the tooltip. |
| `closeDelay` | `number` | No | The close delay of the tooltip. |
| `closeOnClick` | `boolean` | No | Whether the tooltip should close on click |
| `closeOnEscape` | `boolean` | No | Whether to close the tooltip when the Escape key is pressed. |
| `closeOnPointerDown` | `boolean` | No | Whether to close the tooltip on pointerdown. |
| `closeOnScroll` | `boolean` | No | Whether the tooltip should close on scroll |
| `defaultOpen` | `boolean` | No | The initial open state of the tooltip when rendered.
Use when you don't need to control the open state of the tooltip. |
| `disabled` | `boolean` | No | Whether the tooltip is disabled |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{ trigger: string; content: string; arrow: string; positioner: string }>` | No | The ids of the elements in the tooltip. Useful for composition. |
| `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame |
| `interactive` | `boolean` | No | Whether the tooltip's content is interactive.
In this mode, the tooltip will remain open when user hovers over the content. |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state |
| `onOpenChange` | `(details: OpenChangeDetails) => void` | No | Function called when the tooltip is opened. |
| `open` | `boolean` | No | The controlled open state of the tooltip |
| `openDelay` | `number` | No | The open delay of the tooltip. |
| `positioning` | `PositioningOptions` | No | The user provided options used to position the popover content |
| `present` | `boolean` | No | Whether the node is present (controlled by the user) |
| `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


**Arrow Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Arrow CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--arrow-size` | The size of the arrow |
| `--arrow-size-half` | Half the size of the arrow |
| `--arrow-background` | Use this variable to style the arrow background |
| `--arrow-offset` | The offset position of the arrow |


**ArrowTip Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tooltip |
| `[data-part]` | content |
| `[data-state]` | "open" | "closed" |
| `[data-instant]` |  |
| `[data-placement]` | The placement of the content |


**Positioner Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Positioner CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--reference-width` | The width of the reference element |
| `--reference-height` | The height of the root |
| `--available-width` | The available width in viewport |
| `--available-height` | The available height in viewport |
| `--x` | The x position for transform |
| `--y` | The y position for transform |
| `--z-index` | The z-index value |
| `--transform-origin` | The transform origin for animations |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseTooltipReturn` | Yes |  |
| `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state |
| `present` | `boolean` | No | Whether the node is present (controlled by the user) |
| `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


**Trigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tooltip |
| `[data-part]` | trigger |
| `[data-expanded]` | Present when expanded |
| `[data-state]` | "open" | "closed" |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `open` | `boolean` | Whether the tooltip is open. |
| `setOpen` | `(open: boolean) => void` | Function to open the tooltip. |
| `reposition` | `(options?: Partial<PositioningOptions>) => void` | Function to reposition the popover |


## 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 



## Anatomy



```tsx
const tour = useTour({ steps: [...] })

<Tour.Root tour={tour}>
  <Tour.Backdrop />
  <Tour.Spotlight />
  <Tour.Positioner>
    <Tour.Content>
      <Tour.Arrow>
        <Tour.ArrowTip />
      </Tour.Arrow>
      <Tour.Title />
      <Tour.Description />
      <Tour.ProgressText />
      <Tour.CloseTrigger />
      <Tour.Actions>
        <Tour.ActionTrigger />
      </Tour.Actions>
    </Tour.Content>
  </Tour.Positioner>
</Tour.Root>
```

## Examples

**Example: basic**

```ripple
import { Tour, useTour } from 'ark-ripple/tour';
import { Portal } from 'ark-ripple/portal';
import { Ellipsis, Save, Sparkles, Upload, X } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/tour.module.css';

const steps: Tour.StepDetails[] = [
  {
    id: 'welcome',
    type: 'dialog',
    title: 'Welcome to the App!',
    description: 'Let\'s take a quick tour to get you started with the main features.',
    actions: [
      { label: 'Start Tour', action: 'next' },
    ],
  },
  {
    id: 'upload',
    type: 'tooltip',
    title: 'Upload Files',
    description: 'Click here to upload your files to the cloud.',
    target: () => document.querySelector<HTMLElement>('#btn-upload'),
    actions: [
      { label: 'Back', action: 'prev' },
      { label: 'Next', action: 'next' },
    ],
  },
  {
    id: 'save',
    type: 'tooltip',
    title: 'Save Changes',
    description: 'Save your work to keep your progress.',
    target: () => document.querySelector<HTMLElement>('#btn-save'),
    actions: [
      { label: 'Back', action: 'prev' },
      { label: 'Next', action: 'next' },
    ],
  },
  {
    id: 'more',
    type: 'tooltip',
    title: 'More Options',
    description: 'Access additional settings and actions from this menu.',
    target: () => document.querySelector<HTMLElement>('#btn-more'),
    actions: [
      { label: 'Back', action: 'prev' },
      { label: 'Next', action: 'next' },
    ],
  },
  {
    id: 'complete',
    type: 'dialog',
    title: 'You\'re all set!',
    description: 'You now know the basics. Enjoy using the app!',
    actions: [
      { label: 'Finish', action: 'dismiss' },
    ],
  },
];

export component Basic() {
  const tour = useTour({ steps });

  <div class={styles.Root}>
    <button
      type="button"
      data-variant="surface"
      class={button.Root}
      onClick={() => {
        @tour.start();
      }}
    >
      <Sparkles />
      {'Start Tour'}
    </button>

    <div class={styles.ActionButtons}>
      <button id="btn-upload" type="button" class={button.Root}>
        <Upload />
        {'Upload'}
      </button>
      <button id="btn-save" type="button" class={button.Root}>
        <Save />
        {'Save'}
      </button>
      <button id="btn-more" type="button" class={button.Root}>
        <Ellipsis />
        {'More'}
      </button>
    </div>

    <Tour.Root {tour}>
      <Portal>
        <Tour.Backdrop class={styles.Backdrop} />
        <Tour.Spotlight class={styles.Spotlight} />
        <Tour.Positioner class={styles.Positioner}>
          <Tour.Content class={styles.Content}>
            <Tour.Arrow class={styles.Arrow}>
              <Tour.ArrowTip class={styles.ArrowTip} />
            </Tour.Arrow>
            <Tour.CloseTrigger class={styles.CloseTrigger}>
              <X />
            </Tour.CloseTrigger>
            <Tour.ProgressText class={styles.ProgressText} />
            <Tour.Title class={styles.Title} />
            <Tour.Description class={styles.Description} />
            <Tour.Control class={styles.Control}>
              <Tour.Actions>
                component children({ actions }) {
                  for (const action of @actions; key action.label) {
                    <Tour.ActionTrigger class={styles.ActionTrigger} {action} />
                  }
                }
              </Tour.Actions>
            </Tour.Control>
          </Tour.Content>
        </Tour.Positioner>
      </Portal>
    </Tour.Root>
  </div>
}

```

### Step Types

Demonstrate all three step types in a single tour: `dialog` for welcome/completion, `tooltip` anchored to elements, and
`floating` for fixed-position content.

**Example: mixed-types**

```ripple
import { Tour, useTour } from 'ark-ripple/tour';
import { Portal } from 'ark-ripple/portal';
import { Sparkles, X } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/tour.module.css';

const steps: Tour.StepDetails[] = [
  {
    id: 'welcome',
    type: 'dialog',
    title: 'Welcome!',
    description: 'This tour demonstrates different step types: dialog, tooltip, and floating.',
    actions: [
      { label: 'Start Tour', action: 'next' },
    ],
  },
  {
    id: 'tooltip-step',
    type: 'tooltip',
    title: 'Tooltip Step',
    description: 'This step appears as a tooltip anchored to a specific element.',
    target: () => document.querySelector<HTMLElement>('#target-element'),
    actions: [
      { label: 'Back', action: 'prev' },
      { label: 'Next', action: 'next' },
    ],
  },
  {
    id: 'floating-step',
    type: 'floating',
    placement: 'bottom-end',
    title: 'Floating Step',
    description: 'This step floats at a fixed position on the screen, independent of any target.',
    actions: [
      { label: 'Back', action: 'prev' },
      { label: 'Next', action: 'next' },
    ],
  },
  {
    id: 'complete',
    type: 'dialog',
    title: 'Tour Complete!',
    description: 'You have seen all the different step types available.',
    actions: [
      { label: 'Done', action: 'dismiss' },
    ],
  },
];

export component MixedTypes() {
  const tour = useTour({ steps });

  <div class={styles.Root}>
    <button
      type="button"
      data-variant="surface"
      class={button.Root}
      onClick={() => {
        @tour.start();
      }}
    >
      <Sparkles />
      {'Start Tour'}
    </button>

    <div id="target-element" class={styles.Target}>{'Target Element'}</div>

    <Tour.Root {tour}>
      <Portal>
        <Tour.Backdrop class={styles.Backdrop} />
        <Tour.Spotlight class={styles.Spotlight} />
        <Tour.Positioner class={styles.Positioner}>
          <Tour.Content class={styles.Content}>
            <Tour.Arrow class={styles.Arrow}>
              <Tour.ArrowTip class={styles.ArrowTip} />
            </Tour.Arrow>
            <Tour.CloseTrigger class={styles.CloseTrigger}>
              <X />
            </Tour.CloseTrigger>
            <Tour.ProgressText class={styles.ProgressText} />
            <Tour.Title class={styles.Title} />
            <Tour.Description class={styles.Description} />
            <Tour.Control class={styles.Control}>
              <Tour.Actions>
                component children({ actions }) {
                  for (const action of @actions; key action.label) {
                    <Tour.ActionTrigger class={styles.ActionTrigger} {action} />
                  }
                }
              </Tour.Actions>
            </Tour.Control>
          </Tour.Content>
        </Tour.Positioner>
      </Portal>
    </Tour.Root>
  </div>
}

```

### Progress

Display a visual progress indicator at the bottom of the tour content showing how far along the user is.

**Example: progress-bar**

```ripple
import { Tour, useTour } from 'ark-ripple/tour';
import { Portal } from 'ark-ripple/portal';
import { Sparkles, X } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/tour.module.css';

const steps: Tour.StepDetails[] = [
  {
    id: 'step-1',
    type: 'tooltip',
    title: 'Progress Tracking',
    description: 'Watch the progress bar at the bottom as you navigate.',
    target: () => document.querySelector<HTMLElement>('#progress-1'),
    actions: [
      { label: 'Next', action: 'next' },
    ],
  },
  {
    id: 'step-2',
    type: 'tooltip',
    title: 'Halfway There',
    description: 'The progress bar shows how far along you are.',
    target: () => document.querySelector<HTMLElement>('#progress-2'),
    actions: [
      { label: 'Back', action: 'prev' },
      { label: 'Next', action: 'next' },
    ],
  },
  {
    id: 'step-3',
    type: 'tooltip',
    title: 'Almost Done',
    description: 'One more step to complete the tour.',
    target: () => document.querySelector<HTMLElement>('#progress-3'),
    actions: [
      { label: 'Back', action: 'prev' },
      { label: 'Next', action: 'next' },
    ],
  },
  {
    id: 'step-4',
    type: 'tooltip',
    title: 'Complete!',
    description: 'You have completed all the steps.',
    target: () => document.querySelector<HTMLElement>('#progress-4'),
    actions: [
      { label: 'Back', action: 'prev' },
      { label: 'Finish', action: 'dismiss' },
    ],
  },
];

export component ProgressBar() {
  const tour = useTour({ steps });

  <div class={styles.Root}>
    <button
      type="button"
      data-variant="surface"
      class={button.Root}
      onClick={() => {
        @tour.start();
      }}
    >
      <Sparkles />
      {'Start Tour'}
    </button>

    <div class={styles.ActionButtons}>
      <div id="progress-1" class={styles.Target}>{'Step 1'}</div>
      <div id="progress-2" class={styles.Target}>{'Step 2'}</div>
      <div id="progress-3" class={styles.Target}>{'Step 3'}</div>
      <div id="progress-4" class={styles.Target}>{'Step 4'}</div>
    </div>

    <Tour.Root {tour}>
      <Portal>
        <Tour.Backdrop class={styles.Backdrop} />
        <Tour.Spotlight class={styles.Spotlight} />
        <Tour.Positioner class={styles.Positioner}>
          <Tour.Content class={styles.Content}>
            <Tour.Arrow class={styles.Arrow}>
              <Tour.ArrowTip class={styles.ArrowTip} />
            </Tour.Arrow>
            <Tour.CloseTrigger class={styles.CloseTrigger}>
              <X />
            </Tour.CloseTrigger>
            <Tour.ProgressText class={styles.ProgressText} />
            <Tour.Title class={styles.Title} />
            <Tour.Description class={styles.Description} />
            <Tour.Control class={styles.Control}>
              <Tour.Actions>
                component children({ actions }) {
                  for (const action of @actions; key action.label) {
                    <Tour.ActionTrigger class={styles.ActionTrigger} {action} />
                  }
                }
              </Tour.Actions>
            </Tour.Control>
            <div class={styles.ProgressBarBottom}>
              <div
                class={styles.ProgressFill}
                style={{ width: `${@tour.getProgressPercent()}%` }}
              />
            </div>
          </Tour.Content>
        </Tour.Positioner>
      </Portal>
    </Tour.Root>
  </div>
}

```

### Skip

Allow users to skip the entire tour at any step by adding a skip action.

**Example: skip-tour**

```ripple
import { Tour, useTour } from 'ark-ripple/tour';
import { Portal } from 'ark-ripple/portal';
import { Sparkles, X } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/tour.module.css';

const steps: Tour.StepDetails[] = [
  {
    id: 'step-1',
    type: 'tooltip',
    title: 'First Feature',
    description: 'You can skip this tour at any time using the Skip button.',
    target: () => document.querySelector<HTMLElement>('#item-1'),
    actions: [
      { label: 'Skip', action: 'dismiss' },
      { label: 'Next', action: 'next' },
    ],
  },
  {
    id: 'step-2',
    type: 'tooltip',
    title: 'Second Feature',
    description: 'Continue or skip to end the tour early.',
    target: () => document.querySelector<HTMLElement>('#item-2'),
    actions: [
      { label: 'Skip', action: 'dismiss' },
      { label: 'Back', action: 'prev' },
      { label: 'Next', action: 'next' },
    ],
  },
  {
    id: 'step-3',
    type: 'tooltip',
    title: 'Final Feature',
    description: 'This is the last step of the tour.',
    target: () => document.querySelector<HTMLElement>('#item-3'),
    actions: [
      { label: 'Back', action: 'prev' },
      { label: 'Finish', action: 'dismiss' },
    ],
  },
];

export component SkipTour() {
  const tour = useTour({ steps });

  <div class={styles.Root}>
    <button
      type="button"
      data-variant="surface"
      class={button.Root}
      onClick={() => {
        @tour.start();
      }}
    >
      <Sparkles />
      {'Start Tour'}
    </button>

    <div class={styles.ActionButtons}>
      <div id="item-1" class={styles.Target}>{'Item 1'}</div>
      <div id="item-2" class={styles.Target}>{'Item 2'}</div>
      <div id="item-3" class={styles.Target}>{'Item 3'}</div>
    </div>

    <Tour.Root {tour}>
      <Portal>
        <Tour.Backdrop class={styles.Backdrop} />
        <Tour.Spotlight class={styles.Spotlight} />
        <Tour.Positioner class={styles.Positioner}>
          <Tour.Content class={styles.Content}>
            <Tour.Arrow class={styles.Arrow}>
              <Tour.ArrowTip class={styles.ArrowTip} />
            </Tour.Arrow>
            <Tour.CloseTrigger class={styles.CloseTrigger}>
              <X />
            </Tour.CloseTrigger>
            <Tour.ProgressText class={styles.ProgressText} />
            <Tour.Title class={styles.Title} />
            <Tour.Description class={styles.Description} />
            <Tour.Control class={styles.Control}>
              <Tour.Actions>
                component children({ actions }) {
                  for (const action of @actions; key action.label) {
                    <Tour.ActionTrigger class={styles.ActionTrigger} {action} />
                  }
                }
              </Tour.Actions>
            </Tour.Control>
          </Tour.Content>
        </Tour.Positioner>
      </Portal>
    </Tour.Root>
  </div>
}

```

### Keyboard Navigation

Enable arrow key navigation between tour steps using the `keyboardNavigation` prop.

**Example: keyboard-navigation**

```ripple
import { Tour, useTour } from 'ark-ripple/tour';
import { Portal } from 'ark-ripple/portal';
import { Keyboard, Sparkles, X } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/tour.module.css';

const steps: Tour.StepDetails[] = [
  {
    id: 'step-1',
    type: 'tooltip',
    title: 'Keyboard Navigation',
    description: 'Press the right arrow key (→) to go to the next step.',
    target: () => document.querySelector<HTMLElement>('#key-1'),
    actions: [
      { label: 'Next', action: 'next' },
    ],
  },
  {
    id: 'step-2',
    type: 'tooltip',
    title: 'Go Back',
    description: 'Press the left arrow key (←) to go back.',
    target: () => document.querySelector<HTMLElement>('#key-2'),
    actions: [
      { label: 'Back', action: 'prev' },
      { label: 'Next', action: 'next' },
    ],
  },
  {
    id: 'step-3',
    type: 'tooltip',
    title: 'Close Tour',
    description: 'Press Escape to close the tour at any time.',
    target: () => document.querySelector<HTMLElement>('#key-3'),
    actions: [
      { label: 'Back', action: 'prev' },
      { label: 'Finish', action: 'dismiss' },
    ],
  },
];

export component KeyboardNavigation() {
  const tour = useTour({ steps, keyboardNavigation: true });

  <div class={styles.Root}>
    <button
      type="button"
      data-variant="surface"
      class={button.Root}
      onClick={() => {
        @tour.start();
      }}
    >
      <Sparkles />
      {'Start Tour'}
    </button>

    <p class={styles.Hint}>
      <Keyboard />
      {'Use arrow keys to navigate, Escape to close'}
    </p>

    <div class={styles.ActionButtons}>
      <div id="key-1" class={styles.Target}>{'Step 1'}</div>
      <div id="key-2" class={styles.Target}>{'Step 2'}</div>
      <div id="key-3" class={styles.Target}>{'Step 3'}</div>
    </div>

    <Tour.Root {tour}>
      <Portal>
        <Tour.Backdrop class={styles.Backdrop} />
        <Tour.Spotlight class={styles.Spotlight} />
        <Tour.Positioner class={styles.Positioner}>
          <Tour.Content class={styles.Content}>
            <Tour.Arrow class={styles.Arrow}>
              <Tour.ArrowTip class={styles.ArrowTip} />
            </Tour.Arrow>
            <Tour.CloseTrigger class={styles.CloseTrigger}>
              <X />
            </Tour.CloseTrigger>
            <Tour.ProgressText class={styles.ProgressText} />
            <Tour.Title class={styles.Title} />
            <Tour.Description class={styles.Description} />
            <Tour.Control class={styles.Control}>
              <Tour.Actions>
                component children({ actions }) {
                  for (const action of actions; key action.label) {
                    <Tour.ActionTrigger class={styles.ActionTrigger} {action} />
                  }
                }
              </Tour.Actions>
            </Tour.Control>
          </Tour.Content>
        </Tour.Positioner>
      </Portal>
    </Tour.Root>
  </div>
}

```

### Events

Listen to tour lifecycle events like `onStepChange` and `onStatusChange` to track user progress.

**Example: events**

```ripple
import { Tour, useTour } from 'ark-ripple/tour';
import { Portal } from 'ark-ripple/portal';
import { track } from 'ripple';
import { Sparkles, X } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/tour.module.css';

const steps: Tour.StepDetails[] = [
  {
    id: 'step-1',
    type: 'tooltip',
    title: 'First Step',
    description: 'Watch the event log below as you navigate.',
    target: () => document.querySelector<HTMLElement>('#event-1'),
    actions: [
      { label: 'Next', action: 'next' },
    ],
  },
  {
    id: 'step-2',
    type: 'tooltip',
    title: 'Second Step',
    description: 'Each step change triggers an event.',
    target: () => document.querySelector<HTMLElement>('#event-2'),
    actions: [
      { label: 'Back', action: 'prev' },
      { label: 'Next', action: 'next' },
    ],
  },
  {
    id: 'step-3',
    type: 'tooltip',
    title: 'Final Step',
    description: 'Complete the tour to see the status change.',
    target: () => document.querySelector<HTMLElement>('#event-3'),
    actions: [
      { label: 'Back', action: 'prev' },
      { label: 'Finish', action: 'dismiss' },
    ],
  },
];

export component Events() {
  let logs = track<string[]>([]);

  const tour = useTour(
    {
      steps,
      onStepChange(details) {
        @logs = [...@logs, `Step changed: ${details.stepId}`];
      },
      onStatusChange(details) {
        @logs = [...@logs, `Status: ${details.status}`];
      },
    },
  );

  <div class={styles.Root}>
    <button
      type="button"
      data-variant="surface"
      class={button.Root}
      onClick={() => {
        @tour.start();
      }}
    >
      <Sparkles />
      {'Start Tour'}
    </button>

    <div class={styles.ActionButtons}>
      <div id="event-1" class={styles.Target}>{'Step 1'}</div>
      <div id="event-2" class={styles.Target}>{'Step 2'}</div>
      <div id="event-3" class={styles.Target}>{'Step 3'}</div>
    </div>

    <div class={styles.EventLog}>
      <strong>{'Event Log:'}</strong>
      if (@logs.length === 0) {
        <div class={styles.EventLogItem}>{'Start the tour to see events'}</div>
      } else {
        for (const log of @logs; key log) {
          <div class={styles.EventLogItem}>{log}</div>
        }
      }
    </div>

    <Tour.Root {tour}>
      <Portal>
        <Tour.Backdrop class={styles.Backdrop} />
        <Tour.Spotlight class={styles.Spotlight} />
        <Tour.Positioner class={styles.Positioner}>
          <Tour.Content class={styles.Content}>
            <Tour.Arrow class={styles.Arrow}>
              <Tour.ArrowTip class={styles.ArrowTip} />
            </Tour.Arrow>
            <Tour.CloseTrigger class={styles.CloseTrigger}>
              <X />
            </Tour.CloseTrigger>
            <Tour.ProgressText class={styles.ProgressText} />
            <Tour.Title class={styles.Title} />
            <Tour.Description class={styles.Description} />
            <Tour.Control class={styles.Control}>
              <Tour.Actions>
                component children({ actions }) {
                  for (const action of @actions; key action.label) {
                    <Tour.ActionTrigger class={styles.ActionTrigger} {action} />
                  }
                }
              </Tour.Actions>
            </Tour.Control>
          </Tour.Content>
        </Tour.Positioner>
      </Portal>
    </Tour.Root>
  </div>
}

```

### Wait for Click

Use the `effect` function with `waitForEvent` to wait for user interaction before proceeding to the next step.

**Example: wait-for-click**

```ripple
import { Tour, useTour, waitForEvent } from 'ark-ripple/tour';
import { Portal } from 'ark-ripple/portal';
import { Sparkles, X } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/tour.module.css';

const steps: Tour.StepDetails[] = [
  {
    id: 'intro',
    type: 'dialog',
    title: 'Interactive Tutorial',
    description: 'This tour will guide you through actions. You must complete each step to proceed.',
    actions: [
      { label: 'Begin', action: 'next' },
    ],
  },
  {
    id: 'click-add',
    type: 'tooltip',
    title: 'Click the Add Button',
    description: 'Click the "Add Item" button to continue.',
    target: () => document.querySelector<HTMLElement>('#btn-add'),
    effect({ next, target, show }) {
      show();
      const [promise, cancel] = waitForEvent(target, 'click');
      promise.then(() => next());
      return cancel;
    },
  },
  {
    id: 'click-edit',
    type: 'tooltip',
    title: 'Click the Edit Button',
    description: 'Now click the "Edit" button.',
    target: () => document.querySelector<HTMLElement>('#btn-edit'),
    effect({ next, target, show }) {
      show();
      const [promise, cancel] = waitForEvent(target, 'click');
      promise.then(() => next());
      return cancel;
    },
  },
  {
    id: 'click-delete',
    type: 'tooltip',
    title: 'Click the Delete Button',
    description: 'Finally, click the "Delete" button.',
    target: () => document.querySelector<HTMLElement>('#btn-delete'),
    effect({ next, target, show }) {
      show();
      const [promise, cancel] = waitForEvent(target, 'click');
      promise.then(() => next());
      return cancel;
    },
  },
  {
    id: 'complete',
    type: 'dialog',
    title: 'Well Done!',
    description: 'You completed all the interactive steps.',
    actions: [
      { label: 'Finish', action: 'dismiss' },
    ],
  },
];

export component WaitForClick() {
  const tour = useTour({ steps });

  <div class={styles.Root}>
    <button
      type="button"
      data-variant="surface"
      class={button.Root}
      onClick={() => {
        @tour.start();
      }}
    >
      <Sparkles />
      {'Start Interactive Tour'}
    </button>

    <div class={styles.ActionButtons}>
      <button id="btn-add" type="button" class={button.Root}>{'Add Item'}</button>
      <button id="btn-edit" type="button" class={button.Root}>{'Edit'}</button>
      <button id="btn-delete" type="button" class={button.Root}>{'Delete'}</button>
    </div>

    <Tour.Root {tour}>
      <Portal>
        <Tour.Backdrop class={styles.Backdrop} />
        <Tour.Spotlight class={styles.Spotlight} />
        <Tour.Positioner class={styles.Positioner}>
          <Tour.Content class={styles.Content}>
            <Tour.Arrow class={styles.Arrow}>
              <Tour.ArrowTip class={styles.ArrowTip} />
            </Tour.Arrow>
            <Tour.CloseTrigger class={styles.CloseTrigger}>
              <X />
            </Tour.CloseTrigger>
            <Tour.ProgressText class={styles.ProgressText} />
            <Tour.Title class={styles.Title} />
            <Tour.Description class={styles.Description} />
            <Tour.Control class={styles.Control}>
              <Tour.Actions>
                component children({ actions }) {
                  for (const action of @actions; key action.label) {
                    <Tour.ActionTrigger class={styles.ActionTrigger} {action} />
                  }
                }
              </Tour.Actions>
            </Tour.Control>
          </Tour.Content>
        </Tour.Positioner>
      </Portal>
    </Tour.Root>
  </div>
}

```

### Wait for Input

Create form tutorials that wait for users to enter valid input before advancing.

```ripple
Example not found```

### Wait for Element

Wait for dynamically rendered elements to appear in the DOM before showing a step.

```ripple
Example not found```

### Async

Load data asynchronously and update step content before displaying it using the `effect` function with `show()` and
`update()`.

**Example: async-step**

```ripple
import { Tour, useTour } from 'ark-ripple/tour';
import { Portal } from 'ark-ripple/portal';
import { Sparkles, X } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/tour.module.css';

const steps: Tour.StepDetails[] = [
  {
    id: 'intro',
    type: 'dialog',
    title: 'Async Data Loading',
    description: 'This tour demonstrates loading data before showing a step.',
    actions: [
      { label: 'Next', action: 'next' },
    ],
  },
  {
    id: 'user-info',
    type: 'tooltip',
    title: 'Loading...',
    description: 'Fetching user data...',
    target: () => document.querySelector<HTMLElement>('#user-card'),
    actions: [
      { label: 'Back', action: 'prev' },
      { label: 'Next', action: 'next' },
    ],
    effect({ show, update }) {
      const controller = new AbortController();

      fetch('https://api.github.com/users/segunadebayo', { signal: controller.signal }).then(
        (res) => res.json(),
      ).then((data) => {
        update(
          {
            title: `Welcome, ${data.name || data.login}!`,
            description: `You have ${data.public_repos} public repositories and ${data.followers} followers.`,
          },
        );
        show();
      }).catch(() => {
        update(
          {
            title: 'User Profile',
            description: 'Could not load user data. Please try again.',
          },
        );
        show();
      });

      return () => controller.abort();
    },
  },
  {
    id: 'complete',
    type: 'dialog',
    title: 'Tour Complete',
    description: 'The async step loaded data from the GitHub API before displaying.',
    actions: [
      { label: 'Done', action: 'dismiss' },
    ],
  },
];

export component AsyncStep() {
  const tour = useTour({ steps });

  <div class={styles.Root}>
    <button
      type="button"
      data-variant="surface"
      class={button.Root}
      onClick={() => {
        @tour.start();
      }}
    >
      <Sparkles />
      {'Start Tour'}
    </button>

    <div id="user-card" class={styles.Target}>{'User Profile Card'}</div>

    <Tour.Root {tour}>
      <Portal>
        <Tour.Backdrop class={styles.Backdrop} />
        <Tour.Spotlight class={styles.Spotlight} />
        <Tour.Positioner class={styles.Positioner}>
          <Tour.Content class={styles.Content}>
            <Tour.Arrow class={styles.Arrow}>
              <Tour.ArrowTip class={styles.ArrowTip} />
            </Tour.Arrow>
            <Tour.CloseTrigger class={styles.CloseTrigger}>
              <X />
            </Tour.CloseTrigger>
            <Tour.ProgressText class={styles.ProgressText} />
            <Tour.Title class={styles.Title} />
            <Tour.Description class={styles.Description} />
            <Tour.Control class={styles.Control}>
              <Tour.Actions>
                component children({ actions }) {
                  for (const action of @actions; key action.label) {
                    <Tour.ActionTrigger class={styles.ActionTrigger} {action} />
                  }
                }
              </Tour.Actions>
            </Tour.Control>
          </Tour.Content>
        </Tour.Positioner>
      </Portal>
    </Tour.Root>
  </div>
}

```

## Guides

### 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
    },
  },
]
```

### 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' }],
  },
]
```

### 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',
    // ...
  },
]
```

### Hide 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,
  },
]
```

### Hide 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,
  },
]
```

### 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

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

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

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `tour` | `UseTourReturn` | Yes |  |
| `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state |
| `present` | `boolean` | No | Whether the node is present (controlled by the user) |
| `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


**ActionTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `action` | `StepAction` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ActionTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tour |
| `[data-part]` | action-trigger |
| `[data-type]` | The type of the item |
| `[data-disabled]` | Present when disabled |


**Arrow Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Arrow CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--arrow-size` | The size of the arrow |
| `--arrow-size-half` | Half the size of the arrow |
| `--arrow-background` | Use this variable to style the arrow background |
| `--arrow-offset` | The offset position of the arrow |


**ArrowTip Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Backdrop Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Backdrop Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tour |
| `[data-part]` | backdrop |
| `[data-state]` | "open" | "closed" |
| `[data-type]` | The type of the item |


**Backdrop CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--tour-layer` | The tour layer value for the Backdrop |
| `--layer-index` | The index of the dismissable in the layer stack |


**CloseTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**CloseTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tour |
| `[data-part]` | close-trigger |
| `[data-type]` | The type of the item |


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tour |
| `[data-part]` | content |
| `[data-state]` | "open" | "closed" |
| `[data-nested]` | popover |
| `[data-has-nested]` | popover |
| `[data-type]` | The type of the item |
| `[data-placement]` | The placement of the content |
| `[data-step]` |  |


**Content CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--layer-index` | The index of the dismissable in the layer stack |
| `--nested-layer-count` | The number of nested tours |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Description Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Description Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tour |
| `[data-part]` | description |
| `[data-placement]` | The placement of the description |


**Positioner Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Positioner Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tour |
| `[data-part]` | positioner |
| `[data-type]` | The type of the item |
| `[data-placement]` | The placement of the positioner |


**Positioner CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--tour-layer` | The tour layer value for the Positioner |
| `--reference-width` | The width of the reference element |
| `--reference-height` | The height of the root |
| `--available-width` | The available width in viewport |
| `--available-height` | The available height in viewport |
| `--x` | The x position for transform |
| `--y` | The y position for transform |
| `--z-index` | The z-index value |
| `--transform-origin` | The transform origin for animations |


**ProgressText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Spotlight Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Spotlight CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--tour-layer` | The tour layer value for the Spotlight |


**Title Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Title Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tour |
| `[data-part]` | title |
| `[data-placement]` | The placement of the title |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `open` | `boolean` | Whether the tour is open |
| `totalSteps` | `number` | The total number of steps |
| `stepIndex` | `number` | The index of the current step |
| `step` | `StepDetails` | The current step details |
| `hasNextStep` | `boolean` | Whether there is a next step |
| `hasPrevStep` | `boolean` | Whether there is a previous step |
| `firstStep` | `boolean` | Whether the current step is the first step |
| `lastStep` | `boolean` | Whether the current step is the last step |
| `addStep` | `(step: StepDetails) => void` | Add a new step to the tour |
| `removeStep` | `(id: string) => void` | Remove a step from the tour |
| `updateStep` | `(id: string, stepOverrides: Partial<StepDetails>) => void` | Update a step in the tour with partial details |
| `setSteps` | `(steps: StepDetails[]) => void` | Set the steps of the tour |
| `setStep` | `(id: string) => void` | Set the current step of the tour |
| `start` | `(id?: string) => void` | Start the tour at a specific step (or the first step if not provided) |
| `isValidStep` | `(id: string) => boolean` | Check if a step is valid |
| `isCurrentStep` | `(id: string) => boolean` | Check if a step is visible |
| `next` | `VoidFunction` | Move to the next step |
| `prev` | `VoidFunction` | Move to the previous step |
| `getProgressText` | `() => string` | Returns the progress text |
| `getProgressPercent` | `() => number` | Returns the progress percent |



# Tree View 



## Anatomy



```tsx
<TreeView.Root>
  <TreeView.Label />
  <TreeView.Tree>
    <TreeView.NodeProvider>
      <TreeView.Branch>
        <TreeView.BranchControl>
          <TreeView.BranchIndicator />
          <TreeView.BranchText />
        </TreeView.BranchControl>
        <TreeView.BranchContent>
          <TreeView.BranchIndentGuide />
          <TreeView.Item>
            <TreeView.ItemText />
          </TreeView.Item>
        </TreeView.BranchContent>
      </TreeView.Branch>
    </TreeView.NodeProvider>
  </TreeView.Tree>
</TreeView.Root>
```

## Examples

**Example: basic**

```ripple
import { TreeView, createTreeCollection } from 'ark-ripple/tree-view';
import { ChevronRight, File, Folder, FolderOpen } from 'lucide-ripple';
import styles from 'styles/tree-view.module.css';

interface Node {
  id: string;
  name: string;
  children?: Node[] | undefined;
}

const collection = createTreeCollection<Node>(
  {
    nodeToValue: (node) => node.id,
    nodeToString: (node) => node.name,
    rootNode: {
      id: 'ROOT',
      name: '',
      children: [
        {
          id: 'node_modules',
          name: 'node_modules',
          children: [
            { id: 'node_modules/zag-js', name: 'zag-js' },
            { id: 'node_modules/pandacss', name: 'panda' },
            {
              id: 'node_modules/@types',
              name: '@types',
              children: [
                { id: 'node_modules/@types/react', name: 'react' },
                { id: 'node_modules/@types/react-dom', name: 'react-dom' },
              ],
            },
          ],
        },
        {
          id: 'src',
          name: 'src',
          children: [
            { id: 'src/app.tsx', name: 'app.tsx' },
            { id: 'src/index.ts', name: 'index.ts' },
          ],
        },
        { id: 'panda.config', name: 'panda.config.ts' },
        { id: 'package.json', name: 'package.json' },
        { id: 'renovate.json', name: 'renovate.json' },
        { id: 'readme.md', name: 'README.md' },
      ],
    },
  },
);

component TreeNode(props: { node: Node; indexPath: number[] }) {
  <TreeView.NodeProvider node={props.node} indexPath={props.indexPath}>
    <TreeView.NodeContext>
      component children({ context }) {
        if (props.node.children) {
          <TreeView.Branch class={styles.Branch}>
            <TreeView.BranchControl class={styles.BranchControl}>
              <TreeView.BranchIndicator class={styles.BranchIndicator}>
                <ChevronRight />
              </TreeView.BranchIndicator>
              <TreeView.BranchText class={styles.BranchText}>
                if (@context.expanded) {
                  <FolderOpen />
                } else {
                  <Folder />
                }
                {props.node.name}
              </TreeView.BranchText>
            </TreeView.BranchControl>
            <TreeView.BranchContent class={styles.BranchContent}>
              <TreeView.BranchIndentGuide class={styles.BranchIndentGuide} />
              for (const child of props.node.children; index i; key child.id) {
                <TreeNode node={child} indexPath={[...props.indexPath, i]} />
              }
            </TreeView.BranchContent>
          </TreeView.Branch>
        } else {
          <TreeView.Item class={styles.Item}>
            <TreeView.ItemText class={styles.ItemText}>
              <File />
              {props.node.name}
            </TreeView.ItemText>
          </TreeView.Item>
        }
      }
    </TreeView.NodeContext>
  </TreeView.NodeProvider>
}

export component Basic() {
  <TreeView.Root class={styles.Root} {collection}>
    <TreeView.Label class={styles.Label}>{'Tree'}</TreeView.Label>
    <TreeView.Tree class={styles.Tree}>
      for (const [index, node] of collection.rootNode.children!.entries(); key node.id) {
        <TreeNode {node} indexPath={[index]} />
      }
    </TreeView.Tree>
  </TreeView.Root>
}

```

### Controlled Expanded

Pass the `expandedValue` and `onExpandedChange` props to the `TreeView.Root` component to control the expanded state of
the tree view.

**Example: controlled-expanded**

```ripple
import { TreeView, createTreeCollection } from 'ark-ripple/tree-view';
import { ChevronRight, File, Folder, FolderOpen } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/tree-view.module.css';

interface Node {
  id: string;
  name: string;
  children?: Node[] | undefined;
}

const collection = createTreeCollection<Node>(
  {
    nodeToValue: (node) => node.id,
    nodeToString: (node) => node.name,
    rootNode: {
      id: 'ROOT',
      name: '',
      children: [
        {
          id: 'node_modules',
          name: 'node_modules',
          children: [
            { id: 'node_modules/zag-js', name: 'zag-js' },
            { id: 'node_modules/pandacss', name: 'panda' },
            {
              id: 'node_modules/@types',
              name: '@types',
              children: [
                { id: 'node_modules/@types/react', name: 'react' },
                { id: 'node_modules/@types/react-dom', name: 'react-dom' },
              ],
            },
          ],
        },
        {
          id: 'src',
          name: 'src',
          children: [
            { id: 'src/app.tsx', name: 'app.tsx' },
            { id: 'src/index.ts', name: 'index.ts' },
          ],
        },
        { id: 'panda.config', name: 'panda.config.ts' },
        { id: 'package.json', name: 'package.json' },
        { id: 'renovate.json', name: 'renovate.json' },
        { id: 'readme.md', name: 'README.md' },
      ],
    },
  },
);

component TreeNode(props: { node: Node; indexPath: number[] }) {
  <TreeView.NodeProvider node={props.node} indexPath={props.indexPath}>
    <TreeView.NodeContext>
      component children({ context }) {
        if (props.node.children) {
          <TreeView.Branch class={styles.Branch}>
            <TreeView.BranchControl class={styles.BranchControl}>
              <TreeView.BranchIndicator class={styles.BranchIndicator}>
                <ChevronRight />
              </TreeView.BranchIndicator>
              <TreeView.BranchText class={styles.BranchText}>
                if (@context.expanded) {
                  <FolderOpen />
                } else {
                  <Folder />
                }
                {props.node.name}
              </TreeView.BranchText>
            </TreeView.BranchControl>
            <TreeView.BranchContent class={styles.BranchContent}>
              <TreeView.BranchIndentGuide class={styles.BranchIndentGuide} />
              for (const child of props.node.children; index i; key child.id) {
                <TreeNode node={child} indexPath={[...props.indexPath, i]} />
              }
            </TreeView.BranchContent>
          </TreeView.Branch>
        } else {
          <TreeView.Item class={styles.Item}>
            <TreeView.ItemText class={styles.ItemText}>
              <File />
              {props.node.name}
            </TreeView.ItemText>
          </TreeView.Item>
        }
      }
    </TreeView.NodeContext>
  </TreeView.NodeProvider>
}

export component ControlledExpanded() {
  let expandedValue = track<string[]>(['node_modules']);

  <TreeView.Root
    class={styles.Root}
    {collection}
    {expandedValue}
    onExpandedChange={(details) => {
      @expandedValue = details.expandedValue;
    }}
  >
    <TreeView.Label class={styles.Label}>{'Tree'}</TreeView.Label>
    <TreeView.Tree class={styles.Tree}>
      for (const node of collection.rootNode.children!; index i; key node.id) {
        <TreeNode {node} indexPath={[i]} />
      }
    </TreeView.Tree>
  </TreeView.Root>
}

```

### Controlled Selection

Pass the `selectedValue` and `onSelectionChange` props to the `TreeView.Root` component to control the selected state of
the tree view.

**Example: controlled-selected**

```ripple
import { TreeView, createTreeCollection } from 'ark-ripple/tree-view';
import { ChevronRight, File, Folder, FolderOpen } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/tree-view.module.css';

interface Node {
  id: string;
  name: string;
  children?: Node[] | undefined;
}

const collection = createTreeCollection<Node>(
  {
    nodeToValue: (node) => node.id,
    nodeToString: (node) => node.name,
    rootNode: {
      id: 'ROOT',
      name: '',
      children: [
        {
          id: 'node_modules',
          name: 'node_modules',
          children: [
            { id: 'node_modules/zag-js', name: 'zag-js' },
            { id: 'node_modules/pandacss', name: 'panda' },
            {
              id: 'node_modules/@types',
              name: '@types',
              children: [
                { id: 'node_modules/@types/react', name: 'react' },
                { id: 'node_modules/@types/react-dom', name: 'react-dom' },
              ],
            },
          ],
        },
        {
          id: 'src',
          name: 'src',
          children: [
            { id: 'src/app.tsx', name: 'app.tsx' },
            { id: 'src/index.ts', name: 'index.ts' },
          ],
        },
        { id: 'panda.config', name: 'panda.config.ts' },
        { id: 'package.json', name: 'package.json' },
        { id: 'renovate.json', name: 'renovate.json' },
        { id: 'readme.md', name: 'README.md' },
      ],
    },
  },
);

component TreeNode(props: { node: Node; indexPath: number[] }) {
  <TreeView.NodeProvider node={props.node} indexPath={props.indexPath}>
    <TreeView.NodeContext>
      component children({ context }) {
        if (props.node.children) {
          <TreeView.Branch class={styles.Branch}>
            <TreeView.BranchControl class={styles.BranchControl}>
              <TreeView.BranchIndicator class={styles.BranchIndicator}>
                <ChevronRight />
              </TreeView.BranchIndicator>
              <TreeView.BranchText class={styles.BranchText}>
                if (@context.expanded) {
                  <FolderOpen />
                } else {
                  <Folder />
                }
                {props.node.name}
              </TreeView.BranchText>
            </TreeView.BranchControl>
            <TreeView.BranchContent class={styles.BranchContent}>
              <TreeView.BranchIndentGuide class={styles.BranchIndentGuide} />
              for (const child of props.node.children; index i; key child.id) {
                <TreeNode node={child} indexPath={[...props.indexPath, i]} />
              }
            </TreeView.BranchContent>
          </TreeView.Branch>
        } else {
          <TreeView.Item class={styles.Item}>
            <TreeView.ItemText class={styles.ItemText}>
              <File />
              {props.node.name}
            </TreeView.ItemText>
          </TreeView.Item>
        }
      }
    </TreeView.NodeContext>
  </TreeView.NodeProvider>
}

export component ControlledSelected() {
  let selectedValue = track<string[]>(['package.json']);

  <TreeView.Root
    class={styles.Root}
    {collection}
    {selectedValue}
    onSelectionChange={(details) => {
      @selectedValue = details.selectedValue;
    }}
  >
    <TreeView.Label class={styles.Label}>{'Tree'}</TreeView.Label>
    <TreeView.Tree class={styles.Tree}>
      for (const node of collection.rootNode.children!; index i; key node.id) {
        <TreeNode {node} indexPath={[i]} />
      }
    </TreeView.Tree>
  </TreeView.Root>
}

```

### Root Provider

An alternative way to control the tree view is to use the `RootProvider` component and the `useTreeView` hook. This way
you can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { TreeView, createTreeCollection, useTreeView } from 'ark-ripple/tree-view';
import { ChevronRight, File, Folder, FolderOpen } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/tree-view.module.css';

interface Node {
  id: string;
  name: string;
  children?: Node[] | undefined;
}

const collection = createTreeCollection<Node>(
  {
    nodeToValue: (node) => node.id,
    nodeToString: (node) => node.name,
    rootNode: {
      id: 'ROOT',
      name: '',
      children: [
        {
          id: 'node_modules',
          name: 'node_modules',
          children: [
            { id: 'node_modules/zag-js', name: 'zag-js' },
            { id: 'node_modules/pandacss', name: 'panda' },
            {
              id: 'node_modules/@types',
              name: '@types',
              children: [
                { id: 'node_modules/@types/react', name: 'react' },
                { id: 'node_modules/@types/react-dom', name: 'react-dom' },
              ],
            },
          ],
        },
        {
          id: 'src',
          name: 'src',
          children: [
            { id: 'src/app.tsx', name: 'app.tsx' },
            { id: 'src/index.ts', name: 'index.ts' },
          ],
        },
        { id: 'panda.config', name: 'panda.config.ts' },
        { id: 'package.json', name: 'package.json' },
        { id: 'renovate.json', name: 'renovate.json' },
        { id: 'readme.md', name: 'README.md' },
      ],
    },
  },
);

component TreeNode(props: { node: Node; indexPath: number[] }) {
  <TreeView.NodeProvider node={props.node} indexPath={props.indexPath}>
    <TreeView.NodeContext>
      component children({ context }) {
        if (props.node.children) {
          <TreeView.Branch class={styles.Branch}>
            <TreeView.BranchControl class={styles.BranchControl}>
              <TreeView.BranchIndicator class={styles.BranchIndicator}>
                <ChevronRight />
              </TreeView.BranchIndicator>
              <TreeView.BranchText class={styles.BranchText}>
                if (@context.expanded) {
                  <FolderOpen />
                } else {
                  <Folder />
                }
                {props.node.name}
              </TreeView.BranchText>
            </TreeView.BranchControl>
            <TreeView.BranchContent class={styles.BranchContent}>
              <TreeView.BranchIndentGuide class={styles.BranchIndentGuide} />
              for (const child of props.node.children; index i; key child.id) {
                <TreeNode node={child} indexPath={[...props.indexPath, i]} />
              }
            </TreeView.BranchContent>
          </TreeView.Branch>
        } else {
          <TreeView.Item class={styles.Item}>
            <TreeView.ItemText class={styles.ItemText}>
              <File />
              {props.node.name}
            </TreeView.ItemText>
          </TreeView.Item>
        }
      }
    </TreeView.NodeContext>
  </TreeView.NodeProvider>
}

export component RootProvider() {
  const treeViewApi = useTreeView(track(() => ({ collection })));

  <div class="stack">
    <output>
      {'selected: '}
      {JSON.stringify(@treeViewApi.selectedValue)}
    </output>
    <TreeView.RootProvider class={styles.Root} value={treeViewApi}>
      <TreeView.Label class={styles.Label}>{'Tree'}</TreeView.Label>
      <TreeView.Tree class={styles.Tree}>
        for (const node of collection.rootNode.children!; index i; key node.id) {
          <TreeNode {node} indexPath={[i]} />
        }
      </TreeView.Tree>
    </TreeView.RootProvider>
  </div>
}

```

### Lazy Loading

Lazy loading is a feature that allows the tree view to load children of a node on demand (or async). This helps to
improve the initial load time and memory usage.

To use this, you need to provide the following:

- `loadChildren` — A function that is used to load the children of a node.
- `onLoadChildrenComplete` — A callback that is called when the children of a node are loaded. Used to update the tree
  collection.
- `childrenCount` — A number that indicates the number of children of a branch node.

**Example: async-loading**

```ripple
import { TreeView, createTreeCollection, useTreeViewNodeContext } from 'ark-ripple/tree-view';
import { ChevronRight, File, Folder, FolderOpen, Loader } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/tree-view.module.css';

interface Node {
  id: string;
  name: string;
  children?: Node[];
  childrenCount?: number;
}

const response: Record<string, Node[]> = {
  node_modules: [
    { id: 'zag-js', name: 'zag-js' },
    { id: 'pandacss', name: 'panda' },
    { id: '@types', name: '@types', childrenCount: 2 },
  ],
  'node_modules/@types': [
    { id: 'react', name: 'react' },
    { id: 'react-dom', name: 'react-dom' },
  ],
  src: [
    { id: 'app.tsx', name: 'app.tsx' },
    { id: 'index.ts', name: 'index.ts' },
  ],
};

function loadChildren(details: TreeView.LoadChildrenDetails<Node>): Promise<Node[]> {
  const value = details.valuePath.join('/');
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve(response[value] ?? []);
    }, 500);
  });
}

component TreeBranchIcon() {
  const nodeState = useTreeViewNodeContext();
  if (@nodeState.loading) {
    <Loader class={styles.Loader} />
  } else if (@nodeState.expanded) {
    <FolderOpen />
  } else {
    <Folder />
  }
}

component TreeNode(props: { node: Node; indexPath: number[] }) {
  <TreeView.NodeProvider node={props.node} indexPath={props.indexPath}>
    if (props.node.children || props.node.childrenCount) {
      <TreeView.Branch class={styles.Branch}>
        <TreeView.BranchControl class={styles.BranchControl}>
          <TreeView.BranchIndicator class={styles.BranchIndicator}>
            <ChevronRight />
          </TreeView.BranchIndicator>
          <TreeView.BranchText class={styles.BranchText}>
            <TreeBranchIcon />
            {props.node.name}
          </TreeView.BranchText>
        </TreeView.BranchControl>
        <TreeView.BranchContent class={styles.BranchContent}>
          <TreeView.BranchIndentGuide class={styles.BranchIndentGuide} />
          for (const child of props.node.children || []; index i; key child.id) {
            <TreeNode node={child} indexPath={[...props.indexPath, i]} />
          }
        </TreeView.BranchContent>
      </TreeView.Branch>
    } else {
      <TreeView.Item class={styles.Item}>
        <TreeView.ItemText class={styles.ItemText}>
          <File />
          {props.node.name}
        </TreeView.ItemText>
      </TreeView.Item>
    }
  </TreeView.NodeProvider>
}

const initialCollection = createTreeCollection<Node>(
  {
    nodeToValue: (node) => node.id,
    nodeToString: (node) => node.name,
    rootNode: {
      id: 'ROOT',
      name: '',
      children: [
        { id: 'node_modules', name: 'node_modules', childrenCount: 3 },
        { id: 'src', name: 'src', childrenCount: 2 },
        { id: 'panda.config', name: 'panda.config.ts' },
        { id: 'package.json', name: 'package.json' },
        { id: 'renovate.json', name: 'renovate.json' },
        { id: 'readme.md', name: 'README.md' },
      ],
    },
  },
);

export component AsyncLoading() {
  let collection = track(initialCollection);
  <TreeView.Root
    class={styles.Root}
    {collection}
    {loadChildren}
    onLoadChildrenComplete={(e) => {
      @collection = e.collection;
    }}
  >
    <TreeView.Label class={styles.Label}>{'Tree'}</TreeView.Label>
    <TreeView.Tree class={styles.Tree}>
      for (const node of @collection.rootNode.children!; index i; key node.id) {
        <TreeNode {node} indexPath={[i]} />
      }
    </TreeView.Tree>
  </TreeView.Root>
}

```

### Lazy Mount

Lazy mounting is a feature that allows the content of a tree view to be rendered only when it is expanded. This is
useful for performance optimization, especially when tree content is large or complex. To enable lazy mounting, use the
`lazyMount` prop on the `TreeView.Root` component.

In addition, the `unmountOnExit` prop can be used in conjunction with `lazyMount` to unmount the tree view content when
branches are collapsed, freeing up resources. The next time a branch is expanded, its content will be re-rendered.

**Example: lazy-mount**

```ripple
import { TreeView, createTreeCollection, useTreeViewNodeContext } from 'ark-ripple/tree-view';
import { ChevronRight, File, Folder, FolderOpen } from 'lucide-ripple';
import styles from 'styles/tree-view.module.css';

interface Node {
  id: string;
  name: string;
  children?: Node[] | undefined;
}

const collection = createTreeCollection<Node>(
  {
    nodeToValue: (node) => node.id,
    nodeToString: (node) => node.name,
    rootNode: {
      id: 'ROOT',
      name: '',
      children: [
        {
          id: 'node_modules',
          name: 'node_modules',
          children: [
            { id: 'node_modules/zag-js', name: 'zag-js' },
            { id: 'node_modules/pandacss', name: 'panda' },
            {
              id: 'node_modules/@types',
              name: '@types',
              children: [
                { id: 'node_modules/@types/react', name: 'react' },
                { id: 'node_modules/@types/react-dom', name: 'react-dom' },
              ],
            },
          ],
        },
        {
          id: 'src',
          name: 'src',
          children: [
            { id: 'src/app.tsx', name: 'app.tsx' },
            { id: 'src/index.ts', name: 'index.ts' },
          ],
        },
        { id: 'panda.config', name: 'panda.config.ts' },
        { id: 'package.json', name: 'package.json' },
        { id: 'renovate.json', name: 'renovate.json' },
        { id: 'readme.md', name: 'README.md' },
      ],
    },
  },
);

component TreeBranchIcon() {
  const nodeState = useTreeViewNodeContext();
  if (@nodeState.expanded) {
    <FolderOpen />
  } else {
    <Folder />
  }
}

component TreeNode(props: { node: Node; indexPath: number[] }) {
  <TreeView.NodeProvider node={props.node} indexPath={props.indexPath}>
    if (props.node.children) {
      <TreeView.Branch class={styles.Branch}>
        <TreeView.BranchControl class={styles.BranchControl}>
          <TreeView.BranchIndicator class={styles.BranchIndicator}>
            <ChevronRight />
          </TreeView.BranchIndicator>
          <TreeView.BranchText class={styles.BranchText}>
            <TreeBranchIcon />
            {props.node.name}
          </TreeView.BranchText>
        </TreeView.BranchControl>
        <TreeView.BranchContent class={styles.BranchContent}>
          <TreeView.BranchIndentGuide class={styles.BranchIndentGuide} />
          for (const child of props.node.children; index i; key child.id) {
            <TreeNode node={child} indexPath={[...props.indexPath, i]} />
          }
        </TreeView.BranchContent>
      </TreeView.Branch>
    } else {
      <TreeView.Item class={styles.Item}>
        <TreeView.ItemText class={styles.ItemText}>
          <File />
          {props.node.name}
        </TreeView.ItemText>
      </TreeView.Item>
    }
  </TreeView.NodeProvider>
}

export component LazyMount() {
  <TreeView.Root class={styles.Root} {collection} lazyMount unmountOnExit>
    <TreeView.Label class={styles.Label}>{'Tree'}</TreeView.Label>
    <TreeView.Tree class={styles.Tree}>
      for (const node of collection.rootNode.children!; index i; key node.id) {
        <TreeNode {node} indexPath={[i]} />
      }
    </TreeView.Tree>
  </TreeView.Root>
}

```

### Filtering

Filtering is useful when you have a large tree and you want to filter the nodes to only show the ones that match the
search query. Here's an example that composes the `filter` method from the `TreeCollection` and `useFilter` hook to
filter the nodes.

**Example: filtering**

```ripple
import { useFilter } from 'ark-ripple/locale';
import { TreeView, createTreeCollection, useTreeViewContext } from 'ark-ripple/tree-view';
import { ChevronRight, File, Folder, FolderOpen } from 'lucide-ripple';
import { track } from 'ripple';
import fieldStyles from 'styles/field.module.css';
import styles from 'styles/tree-view.module.css';

interface Node {
  id: string;
  name: string;
  children?: Node[];
}

const initialCollection = createTreeCollection<Node>(
  {
    nodeToValue: (node) => node.id,
    nodeToString: (node) => node.name,
    rootNode: {
      id: 'ROOT',
      name: '',
      children: [
        {
          id: 'node_modules',
          name: 'node_modules',
          children: [
            { id: 'node_modules/zag-js', name: 'zag-js' },
            { id: 'node_modules/pandacss', name: 'panda' },
            {
              id: 'node_modules/@types',
              name: '@types',
              children: [
                { id: 'node_modules/@types/react', name: 'react' },
                { id: 'node_modules/@types/react-dom', name: 'react-dom' },
              ],
            },
          ],
        },
        {
          id: 'src',
          name: 'src',
          children: [
            { id: 'src/app.tsx', name: 'app.tsx' },
            { id: 'src/index.ts', name: 'index.ts' },
          ],
        },
        { id: 'panda.config', name: 'panda.config.ts' },
        { id: 'package.json', name: 'package.json' },
        { id: 'renovate.json', name: 'renovate.json' },
        { id: 'readme.md', name: 'README.md' },
      ],
    },
  },
);

component TreeNode(props: { node: Node; indexPath: number[] }) {
  const treeView = useTreeViewContext();
  const nodeState = @treeView.getNodeState({ node: props.node, indexPath: props.indexPath });

  <TreeView.NodeProvider node={props.node} indexPath={props.indexPath}>
    if (nodeState.isBranch) {
      <TreeView.Branch class={styles.Branch}>
        <TreeView.BranchControl class={styles.BranchControl}>
          <TreeView.BranchIndicator class={styles.BranchIndicator}>
            <ChevronRight />
          </TreeView.BranchIndicator>
          <TreeView.BranchText class={styles.BranchText}>
            if (nodeState.expanded) {
              <FolderOpen />
            } else {
              <Folder />
            }
            {props.node.name}
          </TreeView.BranchText>
        </TreeView.BranchControl>
        <TreeView.BranchContent class={styles.BranchContent}>
          <TreeView.BranchIndentGuide class={styles.BranchIndentGuide} />
          for (const child of props.node.children || []; index i; key child.id) {
            <TreeNode node={child} indexPath={[...props.indexPath, i]} />
          }
        </TreeView.BranchContent>
      </TreeView.Branch>
    } else {
      <TreeView.Item class={styles.Item}>
        <TreeView.ItemText class={styles.ItemText}>
          <File />
          {props.node.name}
        </TreeView.ItemText>
      </TreeView.Item>
    }
  </TreeView.NodeProvider>
}

export component Filtering() {
  const filterApi = useFilter({ sensitivity: 'base' });
  let collection = track(initialCollection);

  const filter = (value: string) => {
    @collection = value.length > 0
      ? initialCollection.filter((node: Node) => @filterApi.contains(node.name, value))
      : initialCollection;
  };

  <div class="stack" style={{ maxWidth: '20rem' }}>
    <input
      class={fieldStyles.Input}
      placeholder="Search"
      onInput={(e: InputEvent) => filter((e.target as HTMLInputElement).value)}
    />
    <TreeView.Root class={styles.Root} {collection}>
      <TreeView.Tree class={styles.Tree}>
        for (const node of @collection.rootNode.children!; index i; key node.id) {
          <TreeNode {node} indexPath={[i]} />
        }
      </TreeView.Tree>
    </TreeView.Root>
  </div>
}

```

### Links

Tree items can be rendered as links to another page or website. This could be useful for documentation sites.

Here's an example that modifies the tree collection to represent an hierarchical link structure. It uses the `asChild`
prop to render the tree items as links, passing the `href` prop to a `<a>` element.

**Example: links**

```ripple
import { TreeView, createTreeCollection } from 'ark-ripple/tree-view';
import { ChevronRight, ExternalLink, File } from 'lucide-ripple';
import styles from 'styles/tree-view.module.css';

interface Node {
  id: string;
  name: string;
  href?: string;
  children?: Node[];
}

const collection = createTreeCollection<Node>(
  {
    nodeToValue: (node) => node.id,
    nodeToString: (node) => node.name,
    rootNode: {
      id: 'ROOT',
      name: '',
      children: [
        {
          id: 'docs',
          name: 'Documentation',
          children: [
            { id: 'docs/getting-started', name: 'Getting Started', href: '/docs/getting-started' },
            { id: 'docs/installation', name: 'Installation', href: '/docs/installation' },
            {
              id: 'docs/components',
              name: 'Components',
              children: [
                {
                  id: 'docs/components/accordion',
                  name: 'Accordion',
                  href: '/docs/components/accordion',
                },
                { id: 'docs/components/dialog', name: 'Dialog', href: '/docs/components/dialog' },
                { id: 'docs/components/menu', name: 'Menu', href: '/docs/components/menu' },
              ],
            },
          ],
        },
        {
          id: 'examples',
          name: 'Examples',
          children: [
            { id: 'examples/react', name: 'React Examples', href: '/examples/react' },
            { id: 'examples/vue', name: 'Vue Examples', href: '/examples/vue' },
            { id: 'examples/solid', name: 'Solid Examples', href: '/examples/solid' },
          ],
        },
        {
          id: 'external',
          name: 'External Links',
          children: [
            {
              id: 'external/github',
              name: 'GitHub Repository',
              href: 'https://github.com/chakra-ui/zag',
            },
            {
              id: 'external/npm',
              name: 'NPM Package',
              href: 'https://www.npmjs.com/package/@zag-js/core',
            },
            { id: 'external/docs', name: 'Official Docs', href: 'https://zagjs.com' },
          ],
        },
        { id: 'readme.md', name: 'README.md', href: '/readme' },
        { id: 'license', name: 'LICENSE', href: '/license' },
      ],
    },
  },
);

component TreeNode(props: { node: Node; indexPath: number[] }) {
  <TreeView.NodeProvider node={props.node} indexPath={props.indexPath}>
    if (props.node.children) {
      <TreeView.Branch class={styles.Branch}>
        <TreeView.BranchControl class={styles.BranchControl}>
          <TreeView.BranchIndicator class={styles.BranchIndicator}>
            <ChevronRight />
          </TreeView.BranchIndicator>
          <TreeView.BranchText class={styles.BranchText}>{props.node.name}</TreeView.BranchText>
        </TreeView.BranchControl>
        <TreeView.BranchContent class={styles.BranchContent}>
          <TreeView.BranchIndentGuide class={styles.BranchIndentGuide} />
          for (const child of props.node.children; index i; key child.id) {
            <TreeNode node={child} indexPath={[...props.indexPath, i]} />
          }
        </TreeView.BranchContent>
      </TreeView.Branch>
    } else {
      <TreeView.Item class={styles.Item}>
        component asChild({ propsFn }) {
          <a {...propsFn({ href: props.node.href })}>
            <TreeView.ItemText class={styles.ItemText}>
              <File />
              {props.node.name}
            </TreeView.ItemText>
            if (props.node.href && props.node.href.startsWith('http')) {
              <ExternalLink size={12} />
            }
          </a>
        }
      </TreeView.Item>
    }
  </TreeView.NodeProvider>
}

export component Links() {
  <TreeView.Root class={styles.Root} {collection}>
    <TreeView.Label class={styles.Label}>{'Docs'}</TreeView.Label>
    <TreeView.Tree class={styles.Tree}>
      for (const node of collection.rootNode.children!; index i; key node.id) {
        <TreeNode {node} indexPath={[i]} />
      }
    </TreeView.Tree>
  </TreeView.Root>
}

```

### Virtualized

For large tree views with thousands of nodes, virtualization can significantly improve performance by only rendering
visible nodes.

Key implementation details:

- Use `useTreeView` hook with `TreeView.RootProvider` for programmatic control
- Pass `scrollToIndexFn` to enable keyboard navigation within the virtualized list
- Use `getVisibleNodes()` to get the flattened list of currently visible nodes

**Example: virtualized**

```ripple
import { TreeView, createTreeCollection, useTreeView } from 'ark-ripple/tree-view';
import { ChevronRight, File, Folder } from 'lucide-ripple';
import { flushSync, track } from 'ripple';
import { createVirtualizer } from '../../../utils/use-virtualizer.ripple';
import button from 'styles/button.module.css';
import styles from 'styles/tree-view.module.css';

interface Node {
  id: string;
  name: string;
  children?: Node[];
}

function generateLargeTree(): Node {
  const folders: Node[] = [];
  for (let i = 0; i < 50; i++) {
    const children: Node[] = [];
    for (let j = 0; j < 20; j++) {
      children.push({ id: `folder-${i}/file-${i}-${j}.ts`, name: `file-${i}-${j}.ts` });
    }
    folders.push({ id: `folder-${i}`, name: `folder-${i}`, children });
  }
  return {
    id: 'ROOT',
    name: '',
    children: folders,
  };
}

const collection = createTreeCollection<Node>(
  {
    nodeToValue: (node) => node.id,
    nodeToString: (node) => node.name,
    rootNode: generateLargeTree(),
  },
);

const ROW_HEIGHT = 32;

export component Virtualized() {
  let treeEl = track<HTMLDivElement | null>(null);

  const tree = useTreeView(
    {
      collection,
      scrollToIndexFn(details) {
        flushSync(() => {
          virtualizer.scrollToIndex(details.index, { align: 'auto' });
        });
      },
    },
  );

  const virtualizer = createVirtualizer(
    {
      get count() {
        return @tree.getVisibleNodes().length;
      },
      getScrollElement: () => @treeEl,
      estimateSize: () => ROW_HEIGHT,
      overscan: 10,
    },
  );

  const visibleNodes = track(() => @tree.getVisibleNodes());

  <TreeView.RootProvider class={styles.Root} value={tree}>
    <TreeView.Label class={styles.Label}>
      {'Virtualized Tree ('}
      {@visibleNodes.length}
      {' visible nodes)'}
    </TreeView.Label>
    <div class="hstack">
      <button
        class={button.Root}
        onClick={() => {
          @tree.collapse();
        }}
      >
        {'Collapse all'}
      </button>
      <button
        class={button.Root}
        onClick={() => {
          @tree.expand();
        }}
      >
        {'Expand all'}
      </button>
    </div>
    <TreeView.Tree
      class={styles.Tree}
      {ref (el: HTMLDivElement) => {
        @treeEl = el;
      }}
      style={{ height: '400px', overflow: 'auto' }}
    >
      <div
        style={{
          minHeight: `${virtualizer.getTotalSize()}px`,
          width: '100%',
          position: 'relative',
        }}
      >
        for (const virtualItem of virtualizer.getVirtualItems(); index index; key index) {
          const item = track(() => @visibleNodes[virtualItem.index]);
          const node = track(() => @item.node);
          const indexPath = track(() => @item.indexPath);
          const nodeState = track(() => @tree.getNodeState({ node: @node, indexPath: @indexPath }));
          <div
            data-index={virtualItem.index}
            onPointerDown={(e: PointerEvent) => {
              if (e.button !== 0) return;
              @tree.focus(@node.id);
            }}
            style={{
              position: 'absolute',
              top: '0',
              left: '0',
              width: '100%',
              height: `${virtualItem.size}px`,
              transform: `translateY(${virtualItem.start}px)`,
            }}
          >
            <TreeView.NodeProvider {node} {indexPath}>
              if (@nodeState.isBranch) {
                <TreeView.BranchControl
                  class={styles.BranchControl}
                  style={{ paddingLeft: `${@nodeState.depth * 22}px` }}
                >
                  <TreeView.BranchIndicator class={styles.BranchIndicator}>
                    <ChevronRight />
                  </TreeView.BranchIndicator>
                  <TreeView.BranchText class={styles.BranchText}>
                    <Folder />
                    {@node.name}
                  </TreeView.BranchText>
                </TreeView.BranchControl>
              } else {
                <TreeView.Item
                  class={styles.Item}
                  style={{ paddingLeft: `${@nodeState.depth * 22}px` }}
                >
                  <TreeView.ItemText class={styles.ItemText}>
                    <File />
                    {@node.name}
                  </TreeView.ItemText>
                </TreeView.Item>
              }
            </TreeView.NodeProvider>
          </div>
        }
      </div>
    </TreeView.Tree>
  </TreeView.RootProvider>
}

```

### Checkbox Tree

Use the `defaultCheckedValue` prop to enable checkbox selection mode. This allows users to select multiple nodes with
checkboxes, including parent-child selection relationships.

**Example: checkbox-tree**

```ripple
import { TreeView, createTreeCollection } from 'ark-ripple/tree-view';
import { Check, ChevronRight, Minus } from 'lucide-ripple';
import styles from 'styles/tree-view.module.css';

interface Node {
  id: string;
  name: string;
  children?: Node[] | undefined;
}

const collection = createTreeCollection<Node>(
  {
    nodeToValue: (node) => node.id,
    nodeToString: (node) => node.name,
    rootNode: {
      id: 'ROOT',
      name: '',
      children: [
        {
          id: 'node_modules',
          name: 'node_modules',
          children: [
            { id: 'node_modules/zag-js', name: 'zag-js' },
            { id: 'node_modules/pandacss', name: 'panda' },
            {
              id: 'node_modules/@types',
              name: '@types',
              children: [
                { id: 'node_modules/@types/react', name: 'react' },
                { id: 'node_modules/@types/react-dom', name: 'react-dom' },
              ],
            },
          ],
        },
        {
          id: 'src',
          name: 'src',
          children: [
            { id: 'src/app.tsx', name: 'app.tsx' },
            { id: 'src/index.ts', name: 'index.ts' },
          ],
        },
        { id: 'panda.config', name: 'panda.config.ts' },
        { id: 'package.json', name: 'package.json' },
        { id: 'renovate.json', name: 'renovate.json' },
        { id: 'readme.md', name: 'README.md' },
      ],
    },
  },
);

component TreeNodeCheckbox() {
  <TreeView.NodeCheckbox class={styles.NodeCheckbox}>
    <TreeView.NodeCheckboxIndicator class={styles.NodeCheckboxIndicator} indeterminate={Minus}>
      <Check />
    </TreeView.NodeCheckboxIndicator>
  </TreeView.NodeCheckbox>
}

component TreeNode(props: { node: Node; indexPath: number[] }) {
  <TreeView.NodeProvider node={props.node} indexPath={props.indexPath}>
    if (props.node.children) {
      <TreeView.Branch class={styles.Branch}>
        <TreeView.BranchControl class={styles.BranchControl}>
          <TreeView.BranchIndicator class={styles.BranchIndicator}>
            <ChevronRight />
          </TreeView.BranchIndicator>
          <TreeNodeCheckbox />
          <TreeView.BranchText class={styles.BranchText}>{props.node.name}</TreeView.BranchText>
        </TreeView.BranchControl>
        <TreeView.BranchContent class={styles.BranchContent}>
          <TreeView.BranchIndentGuide class={styles.BranchIndentGuide} />
          for (const child of props.node.children; index i; key child.id) {
            <TreeNode node={child} indexPath={[...props.indexPath, i]} />
          }
        </TreeView.BranchContent>
      </TreeView.Branch>
    } else {
      <TreeView.Item class={styles.Item}>
        <TreeNodeCheckbox />
        <TreeView.ItemText class={styles.ItemText}>{props.node.name}</TreeView.ItemText>
      </TreeView.Item>
    }
  </TreeView.NodeProvider>
}

export component CheckboxTree() {
  <TreeView.Root class={styles.Root} {collection} defaultCheckedValue={[]}>
    <TreeView.Label class={styles.Label}>{'Tree'}</TreeView.Label>
    <TreeView.Tree class={styles.Tree}>
      for (const node of collection.rootNode.children!; index i; key node.id) {
        <TreeNode {node} indexPath={[i]} />
      }
    </TreeView.Tree>
  </TreeView.Root>
}

```

### Expand and Collapse All

Use the `expand()` and `collapse()` methods from the tree view context to programmatically expand or collapse all
branches.

**Example: expand-collapse-all**

```ripple
import { TreeView, createTreeCollection, useTreeViewContext } from 'ark-ripple/tree-view';
import { track } from 'ripple';
import { ChevronRight, File, Folder, FolderOpen } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/tree-view.module.css';

interface Node {
  id: string;
  name: string;
  children?: Node[];
}

const collection = createTreeCollection<Node>(
  {
    nodeToValue: (node) => node.id,
    nodeToString: (node) => node.name,
    rootNode: {
      id: 'ROOT',
      name: '',
      children: [
        {
          id: 'node_modules',
          name: 'node_modules',
          children: [
            { id: 'node_modules/zag-js', name: 'zag-js' },
            { id: 'node_modules/pandacss', name: 'panda' },
            {
              id: 'node_modules/@types',
              name: '@types',
              children: [
                { id: 'node_modules/@types/react', name: 'react' },
                { id: 'node_modules/@types/react-dom', name: 'react-dom' },
              ],
            },
          ],
        },
        {
          id: 'src',
          name: 'src',
          children: [
            { id: 'src/app.tsx', name: 'app.tsx' },
            { id: 'src/index.ts', name: 'index.ts' },
          ],
        },
        { id: 'panda.config', name: 'panda.config.ts' },
        { id: 'package.json', name: 'package.json' },
        { id: 'renovate.json', name: 'renovate.json' },
        { id: 'readme.md', name: 'README.md' },
      ],
    },
  },
);

component ExpandCollapseButtons() {
  const tree = useTreeViewContext();
  let isAllExpanded = track(() => {
    const branchValues = @tree.collection.getBranchValues();
    return branchValues.every((value: string) => @tree.expandedValue.includes(value));
  });

  <div class="hstack">
    if (@isAllExpanded) {
      <button
        class={button.Root}
        onClick={() => {
          @tree.collapse();
        }}
      >
        {'Collapse all'}
      </button>
    } else {
      <button
        class={button.Root}
        onClick={() => {
          @tree.expand();
        }}
      >
        {'Expand all'}
      </button>
    }
  </div>
}

component TreeNode(props: { node: Node; indexPath: number[] }) {
  <TreeView.NodeProvider node={props.node} indexPath={props.indexPath}>
    <TreeView.NodeContext>
      component children({ context }) {
        if (props.node.children) {
          <TreeView.Branch class={styles.Branch}>
            <TreeView.BranchControl class={styles.BranchControl}>
              <TreeView.BranchIndicator class={styles.BranchIndicator}>
                <ChevronRight />
              </TreeView.BranchIndicator>
              <TreeView.BranchText class={styles.BranchText}>
                if (@context.expanded) {
                  <FolderOpen />
                } else {
                  <Folder />
                }
                {props.node.name}
              </TreeView.BranchText>
            </TreeView.BranchControl>
            <TreeView.BranchContent class={styles.BranchContent}>
              <TreeView.BranchIndentGuide class={styles.BranchIndentGuide} />
              for (const child of props.node.children; index i; key child.id) {
                <TreeNode node={child} indexPath={[...props.indexPath, i]} />
              }
            </TreeView.BranchContent>
          </TreeView.Branch>
        } else {
          <TreeView.Item class={styles.Item}>
            <TreeView.ItemText class={styles.ItemText}>
              <File />
              {props.node.name}
            </TreeView.ItemText>
          </TreeView.Item>
        }
      }
    </TreeView.NodeContext>
  </TreeView.NodeProvider>
}

export component ExpandCollapseAll() {
  <TreeView.Root class={styles.Root} {collection} data-animate="false">
    <ExpandCollapseButtons />
    <TreeView.Tree class={styles.Tree}>
      for (const node of collection.rootNode.children!; index i; key node.id) {
        <TreeNode {node} indexPath={[i]} />
      }
    </TreeView.Tree>
  </TreeView.Root>
}

```

### Mutation

Use the collection's `remove()` and `replace()` methods to dynamically add and remove nodes from the tree. This is
useful for building file explorer interfaces where users can create and delete files.

**Example: mutation**

```ripple
import { TreeView, createTreeCollection, useTreeViewContext } from 'ark-ripple/tree-view';
import { ChevronRight, Plus, Trash } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/tree-view.module.css';

interface Node {
  id: string;
  name: string;
  children?: Node[];
}

interface TreeNodeProps {
  node: Node;
  indexPath: number[];
  onRemove?: (props: { node: Node; indexPath: number[] }) => void;
  onAdd?: (props: { node: Node; indexPath: number[] }) => void;
}

const initialCollection = createTreeCollection<Node>(
  {
    nodeToValue: (node) => node.id,
    nodeToString: (node) => node.name,
    rootNode: {
      id: 'ROOT',
      name: '',
      children: [
        {
          id: 'node_modules',
          name: 'node_modules',
          children: [
            { id: 'node_modules/zag-js', name: 'zag-js' },
            { id: 'node_modules/pandacss', name: 'panda' },
            {
              id: 'node_modules/@types',
              name: '@types',
              children: [
                { id: 'node_modules/@types/react', name: 'react' },
                { id: 'node_modules/@types/react-dom', name: 'react-dom' },
              ],
            },
          ],
        },
        {
          id: 'src',
          name: 'src',
          children: [
            { id: 'src/app.tsx', name: 'app.tsx' },
            { id: 'src/index.ts', name: 'index.ts' },
          ],
        },
        { id: 'panda.config', name: 'panda.config.ts' },
        { id: 'package.json', name: 'package.json' },
        { id: 'renovate.json', name: 'renovate.json' },
        { id: 'readme.md', name: 'README.md' },
      ],
    },
  },
);

component TreeNodeActions(props: TreeNodeProps) {
  const tree = useTreeViewContext();
  const isBranch = @tree.collection.isBranchNode(props.node);

  <div class={styles.ActionGroup}>
    <button
      class={styles.Action}
      onClick={(e: MouseEvent) => {
        e.stopPropagation();
        props.onRemove?.(props);
      }}
    >
      <Trash />
    </button>
    if (isBranch) {
      <button
        class={styles.Action}
        onClick={(e: MouseEvent) => {
          e.stopPropagation();
          props.onAdd?.(props);
          @tree.expand([props.node.id]);
        }}
      >
        <Plus />
      </button>
    }
  </div>
}

component TreeNode(props: TreeNodeProps) {
  const tree = useTreeViewContext();
  const nodeState = @tree.getNodeState({ node: props.node, indexPath: props.indexPath });

  <TreeView.NodeProvider node={props.node} indexPath={props.indexPath}>
    if (nodeState.isBranch) {
      <TreeView.Branch class={styles.Branch}>
        <TreeView.BranchControl class={styles.BranchControl}>
          <TreeView.BranchIndicator class={styles.BranchIndicator}>
            <ChevronRight />
          </TreeView.BranchIndicator>
          <TreeView.BranchText class={styles.BranchText}>{props.node.name}</TreeView.BranchText>
          <TreeNodeActions {...props} />
        </TreeView.BranchControl>
        <TreeView.BranchContent class={styles.BranchContent}>
          <TreeView.BranchIndentGuide class={styles.BranchIndentGuide} />
          for (const child of props.node.children || []; index i; key child.id) {
            <TreeNode
              node={child}
              indexPath={[...props.indexPath, i]}
              onRemove={props.onRemove}
              onAdd={props.onAdd}
            />
          }
        </TreeView.BranchContent>
      </TreeView.Branch>
    } else {
      <TreeView.Item class={styles.Item}>
        <TreeView.ItemText class={styles.ItemText}>{props.node.name}</TreeView.ItemText>
        <TreeNodeActions {...props} />
      </TreeView.Item>
    }
  </TreeView.NodeProvider>
}

export component Mutation() {
  let collection = track(initialCollection);

  const removeNode = (props: { node: Node; indexPath: number[] }) => {
    @collection = @collection.remove([props.indexPath]);
  };

  const addNode = (props: { node: Node; indexPath: number[] }) => {
    const { node, indexPath } = props;
    if (!@collection.isBranchNode(node)) return;
    const children = [
      { id: `untitled-${Date.now()}`, name: 'untitled.tsx' },
      ...node.children || [],
    ];
    @collection = @collection.replace(indexPath, { ...node, children });
  };

  <TreeView.Root class={styles.Root} {collection}>
    <TreeView.Tree class={styles.Tree}>
      for (const node of @collection.rootNode.children!; index i; key node.id) {
        <TreeNode {node} indexPath={[i]} onRemove={removeNode} onAdd={addNode} />
      }
    </TreeView.Tree>
  </TreeView.Root>
}

```

### Rename Node

Enable inline renaming of nodes using the `canRename` prop and `onRenameComplete` callback. Press <kbd>F2</kbd> to
activate rename mode on the focused node.

**Example: rename-node**

```ripple
import { TreeView, createTreeCollection } from 'ark-ripple/tree-view';
import { ChevronRight, File, Folder, FolderOpen } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/tree-view.module.css';

interface Node {
  id: string;
  name: string;
  children?: Node[];
}

const initialCollection = createTreeCollection<Node>(
  {
    nodeToValue: (node) => node.id,
    nodeToString: (node) => node.name,
    rootNode: {
      id: 'ROOT',
      name: '',
      children: [
        {
          id: 'node_modules',
          name: 'node_modules',
          children: [
            { id: 'node_modules/zag-js', name: 'zag-js' },
            { id: 'node_modules/pandacss', name: 'panda' },
            {
              id: 'node_modules/@types',
              name: '@types',
              children: [
                { id: 'node_modules/@types/react', name: 'react' },
                { id: 'node_modules/@types/react-dom', name: 'react-dom' },
              ],
            },
          ],
        },
        {
          id: 'src',
          name: 'src',
          children: [
            { id: 'src/app.tsx', name: 'app.tsx' },
            { id: 'src/index.ts', name: 'index.ts' },
          ],
        },
        { id: 'panda.config', name: 'panda.config.ts' },
        { id: 'package.json', name: 'package.json' },
        { id: 'renovate.json', name: 'renovate.json' },
        { id: 'readme.md', name: 'README.md' },
      ],
    },
  },
);

component TreeNode(props: { node: Node; indexPath: number[] }) {
  <TreeView.NodeProvider node={props.node} indexPath={props.indexPath}>
    <TreeView.NodeContext>
      component children({ context }) {
        if (props.node.children) {
          <TreeView.Branch class={styles.Branch}>
            <TreeView.BranchControl class={styles.BranchControl}>
              <TreeView.BranchIndicator class={styles.BranchIndicator}>
                <ChevronRight />
              </TreeView.BranchIndicator>
              if (@context.renaming) {
                <TreeView.NodeRenameInput class={styles.NodeRenameInput} />
              } else {
                <TreeView.BranchText class={styles.BranchText}>
                  if (@context.expanded) {
                    <FolderOpen />
                  } else {
                    <Folder />
                  }
                  {props.node.name}
                </TreeView.BranchText>
              }
            </TreeView.BranchControl>
            <TreeView.BranchContent class={styles.BranchContent}>
              <TreeView.BranchIndentGuide class={styles.BranchIndentGuide} />
              for (const child of props.node.children; index i; key child.id) {
                <TreeNode node={child} indexPath={[...props.indexPath, i]} />
              }
            </TreeView.BranchContent>
          </TreeView.Branch>
        } else {
          <TreeView.Item class={styles.Item}>
            <File />
            if (@context.renaming) {
              <TreeView.NodeRenameInput class={styles.NodeRenameInput} />
            } else {
              <TreeView.ItemText class={styles.ItemText}>{props.node.name}</TreeView.ItemText>
            }
          </TreeView.Item>
        }
      }
    </TreeView.NodeContext>
  </TreeView.NodeProvider>
}

export component RenameNode() {
  let collection = track(initialCollection);
  <TreeView.Root
    class={styles.Root}
    {collection}
    canRename={() => true}
    onRenameComplete={(details) => {
      const node = @collection.at(details.indexPath);
      if (!node) return;
      @collection = @collection.replace(details.indexPath, { ...node, name: details.label });
    }}
  >
    <TreeView.Label class={styles.Label}>{'Tree (Press F2 to rename)'}</TreeView.Label>
    <TreeView.Tree class={styles.Tree}>
      for (const node of @collection.rootNode.children!; index i; key node.id) {
        <TreeNode {node} indexPath={[i]} />
      }
    </TreeView.Tree>
  </TreeView.Root>
}

```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `collection` | `TreeCollection<T>` | Yes | The collection of tree nodes |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `canRename` | `(node: T, indexPath: IndexPath) => boolean` | No | Function to determine if a node can be renamed |
| `checkedValue` | `string[]` | No | The controlled checked node value |
| `defaultCheckedValue` | `string[]` | No | The initial checked node value when rendered.
Use when you don't need to control the checked node value. |
| `defaultExpandedValue` | `string[]` | No | The initial expanded node ids when rendered.
Use when you don't need to control the expanded node value. |
| `defaultFocusedValue` | `string` | No | The initial focused node value when rendered.
Use when you don't need to control the focused node value. |
| `defaultSelectedValue` | `string[]` | No | The initial selected node value when rendered.
Use when you don't need to control the selected node value. |
| `expandedValue` | `string[]` | No | The controlled expanded node ids |
| `expandOnClick` | `boolean` | No | Whether clicking on a branch should open it or not |
| `focusedValue` | `string` | No | The value of the focused node |
| `ids` | `Partial<{ root: string; tree: string; label: string; node: (value: string) => string }>` | No | The ids of the tree elements. Useful for composition. |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `loadChildren` | `(details: LoadChildrenDetails<T>) => Promise<T[]>` | No | Function to load children for a node asynchronously.
When provided, branches will wait for this promise to resolve before expanding. |
| `onBeforeRename` | `(details: RenameCompleteDetails) => boolean` | No | Called before a rename is completed. Return false to prevent the rename. |
| `onCheckedChange` | `(details: CheckedChangeDetails) => void` | No | Called when the checked value changes |
| `onExpandedChange` | `(details: ExpandedChangeDetails<T>) => void` | No | Called when the tree is opened or closed |
| `onFocusChange` | `(details: FocusChangeDetails<T>) => void` | No | Called when the focused node changes |
| `onLoadChildrenComplete` | `(details: LoadChildrenCompleteDetails<T>) => void` | No | Called when a node finishes loading children |
| `onLoadChildrenError` | `(details: LoadChildrenErrorDetails<T>) => void` | No | Called when loading children fails for one or more nodes |
| `onRenameComplete` | `(details: RenameCompleteDetails) => void` | No | Called when a node label rename is completed |
| `onRenameStart` | `(details: RenameStartDetails<T>) => void` | No | Called when a node starts being renamed |
| `onSelectionChange` | `(details: SelectionChangeDetails<T>) => void` | No | Called when the selection changes |
| `scrollToIndexFn` | `(details: ScrollToIndexDetails<T>) => void` | No | Function to scroll to a specific index.
Useful for virtualized tree views. |
| `selectedValue` | `string[]` | No | The controlled selected node value |
| `selectionMode` | `'multiple' | 'single'` | No | Whether the tree supports multiple selection
- "single": only one node can be selected
- "multiple": multiple nodes can be selected |
| `typeahead` | `boolean` | No | Whether the tree supports typeahead search |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


**BranchContent Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**BranchContent Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tree-view |
| `[data-part]` | branch-content |
| `[data-state]` | "open" | "closed" |
| `[data-depth]` | The depth of the item |
| `[data-path]` | The path of the item |
| `[data-value]` | The value of the item |


**BranchControl Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**BranchControl Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tree-view |
| `[data-part]` | branch-control |
| `[data-path]` | The path of the item |
| `[data-state]` | "open" | "closed" |
| `[data-disabled]` | Present when disabled |
| `[data-selected]` | Present when selected |
| `[data-focus]` | Present when focused |
| `[data-renaming]` |  |
| `[data-value]` | The value of the item |
| `[data-depth]` | The depth of the item |
| `[data-loading]` | Present when loading |


**BranchIndentGuide Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**BranchIndentGuide Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tree-view |
| `[data-part]` | branch-indent-guide |
| `[data-depth]` | The depth of the item |


**BranchIndicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**BranchIndicator Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tree-view |
| `[data-part]` | branch-indicator |
| `[data-state]` | "open" | "closed" |
| `[data-disabled]` | Present when disabled |
| `[data-selected]` | Present when selected |
| `[data-focus]` | Present when focused |
| `[data-loading]` | Present when loading |


**Branch Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Branch Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tree-view |
| `[data-part]` | branch |
| `[data-depth]` | The depth of the item |
| `[data-branch]` |  |
| `[data-value]` | The value of the item |
| `[data-path]` | The path of the item |
| `[data-selected]` | Present when selected |
| `[data-state]` | "open" | "closed" |
| `[data-disabled]` | Present when disabled |
| `[data-loading]` | Present when loading |


**Branch CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--depth` | The depth value for the Branch |


**BranchText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**BranchText Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tree-view |
| `[data-part]` | branch-text |
| `[data-disabled]` | Present when disabled |
| `[data-state]` | "open" | "closed" |
| `[data-loading]` | Present when loading |


**BranchTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**BranchTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tree-view |
| `[data-part]` | branch-trigger |
| `[data-disabled]` | Present when disabled |
| `[data-state]` | "open" | "closed" |
| `[data-value]` | The value of the item |
| `[data-loading]` | Present when loading |


**ItemIndicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemIndicator Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tree-view |
| `[data-part]` | item-indicator |
| `[data-disabled]` | Present when disabled |
| `[data-selected]` | Present when selected |
| `[data-focus]` | Present when focused |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Item Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tree-view |
| `[data-part]` | item |
| `[data-path]` | The path of the item |
| `[data-value]` | The value of the item |
| `[data-focus]` | Present when focused |
| `[data-selected]` | Present when selected |
| `[data-disabled]` | Present when disabled |
| `[data-renaming]` |  |
| `[data-depth]` | The depth of the item |


**Item CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--depth` | The depth value for the Item |


**ItemText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemText Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tree-view |
| `[data-part]` | item-text |
| `[data-disabled]` | Present when disabled |
| `[data-selected]` | Present when selected |
| `[data-focus]` | Present when focused |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**NodeCheckboxIndicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `fallback` | `string | number | bigint | boolean | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...>` | No |  |
| `indeterminate` | `string | number | bigint | boolean | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...>` | No |  |


**NodeCheckbox Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**NodeCheckbox Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tree-view |
| `[data-part]` | node-checkbox |
| `[data-state]` | "checked" | "unchecked" | "indeterminate" |
| `[data-disabled]` | Present when disabled |


**NodeProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `indexPath` | `number[]` | Yes | The index path of the tree node |
| `node` | `NonNullable<T>` | No | The tree node |


**NodeRenameInput Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseTreeViewReturn<T>` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


**Tree Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `collection` | `TreeCollection<V>` | The tree collection data |
| `expandedValue` | `string[]` | The value of the expanded nodes. |
| `setExpandedValue` | `(value: string[]) => void` | Sets the expanded value |
| `selectedValue` | `string[]` | The value of the selected nodes. |
| `setSelectedValue` | `(value: string[]) => void` | Sets the selected value |
| `checkedValue` | `string[]` | The value of the checked nodes |
| `toggleChecked` | `(value: string, isBranch: boolean) => void` | Toggles the checked value of a node |
| `setChecked` | `(value: string[]) => void` | Sets the checked value of a node |
| `clearChecked` | `VoidFunction` | Clears the checked value of a node |
| `getCheckedMap` | `() => CheckedValueMap` | Returns the checked details of branch and leaf nodes |
| `getVisibleNodes` | `() => VisibleNode<V>[]` | Returns the visible nodes as a flat array of nodes and their index path.
Useful for rendering virtualized tree views. |
| `expand` | `(value?: string[]) => void` | Function to expand nodes.
If no value is provided, all nodes will be expanded |
| `collapse` | `(value?: string[]) => void` | Function to collapse nodes
If no value is provided, all nodes will be collapsed |
| `select` | `(value?: string[]) => void` | Function to select nodes
If no value is provided, all nodes will be selected |
| `deselect` | `(value?: string[]) => void` | Function to deselect nodes
If no value is provided, all nodes will be deselected |
| `focus` | `(value: string) => void` | Function to focus a node by value |
| `selectParent` | `(value: string) => void` | Function to select the parent node of the focused node |
| `expandParent` | `(value: string) => void` | Function to expand the parent node of the focused node |
| `startRenaming` | `(value: string) => void` | Function to start renaming a node by value |
| `submitRenaming` | `(value: string, label: string) => void` | Function to submit the rename and update the node label |
| `cancelRenaming` | `() => void` | Function to cancel renaming without changes |


## 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.<br> 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.<br> When focus is on an item or branch node, moves focus to its parent branch node.

**`Home`**
Description: Moves focus to first node without opening or closing a node.

**`End`**
Description: Moves focus to the last node that can be focused without expanding any nodes that are closed.

**`a-z + A-Z`**
Description: Focus moves to the next node with a name that starts with the typed character. The search logic ignores nodes that are descendants of closed branch.

**`*`**
Description: Expands all sibling nodes that are at the same depth as the focused node.

**`Shift + ArrowDown`**
Description: Moves focus to and toggles the selection state of the next node.

**`Shift + ArrowUp`**
Description: Moves focus to and toggles the selection state of the previous node.

**`Ctrl + A`**
Description: Selects all nodes in the tree. If all nodes are selected, unselects all nodes.



# UTILITIES

---

# Client Only 

## Motivation

The `ClientOnly` component renders its children only on the client side. This is useful for components that need to
access the DOM or browser APIs that are not available on the server side.

## Examples

### Basic

**Example: basic**

```ripple
import { ClientOnly } from 'ark-ripple/client-only';

export component Basic() {
  <ClientOnly>
    <div>{'This content is only rendered on the client side.'}</div>
  </ClientOnly>
}

```

### With Fallback

**Example: with-fallback**

```ripple
import { ClientOnly } from 'ark-ripple/client-only';

export component WithFallback() {
  <ClientOnly fallback="Loading...">
    <div>{'This content is only rendered on the client side.'}</div>
  </ClientOnly>
}

```

## API Reference

**Component API Reference**

**ClientOnly Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `fallback` | `any` | No |  |



# Download Trigger 

## Motivation

The `DownloadTrigger` component provides a convenient way to programmatically trigger file downloads in web
applications. It handles the complexities of downloading files, whether they are URLs, Blobs, or other data types.

## Examples

### Basic

Pass the data you want to download to the `data` prop, and specify the `fileName` and `mimeType` of the file.

**Example: basic**

```ripple
import { DownloadTrigger } from 'ark-ripple/download-trigger';
import { Download, File } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/download-trigger.module.css';

const content = 'Hello, World! This is a sample text file.';

export component Basic() {
  <div class={styles.Root}>
    <div class={styles.Preview}>
      <File />
      <span class={styles.PreviewText}>{content}</span>
    </div>
    <DownloadTrigger class={button.Root} data={content} fileName="hello.txt" mimeType="text/plain">
      <Download />
      {' Download txt'}
    </DownloadTrigger>
  </div>
}

```

### Download SVG

Here's an example of how to download an SVG file.

**Example: svg**

```ripple
import { DownloadTrigger } from 'ark-ripple/download-trigger';
import { Download, File } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/download-trigger.module.css';

const svgContent = `<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
  <circle cx="50" cy="50" r="40" stroke="black" stroke-width="3" fill="red"/>
</svg>`;

export component Svg() {
  <div class={styles.Root}>
    <div class={styles.Preview}>
      <File />
      <span class={styles.PreviewText}>{'circle.svg'}</span>
    </div>
    <DownloadTrigger
      class={button.Root}
      data={svgContent}
      fileName="circle.svg"
      mimeType="image/svg+xml"
    >
      <Download />
      {' Download SVG'}
    </DownloadTrigger>
  </div>
}

```

### Promise

You can also trigger downloads from a promise that returns a `Blob`, `File`, or `string`.

**Example: with-promise**

```ripple
import { DownloadTrigger } from 'ark-ripple/download-trigger';
import { Download, Image } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/download-trigger.module.css';

const fetchImage = async () => {
  const response = await fetch('https://picsum.photos/200/300');
  return response.blob();
};

export component WithPromise() {
  <div class={styles.Root}>
    <div class={styles.Preview}>
      <Image />
      <span class={styles.PreviewText}>{'random-image.jpg (fetched on download)'}</span>
    </div>
    <DownloadTrigger
      class={button.Root}
      data={fetchImage}
      fileName="random-image.jpg"
      mimeType="image/jpeg"
    >
      <Download />
      {' Download Image'}
    </DownloadTrigger>
  </div>
}

```

## API Reference

**Component API Reference**

**DownloadTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `data` | `DownloadableData | (() => MaybePromise<DownloadableData>)` | Yes | The data to download |
| `fileName` | `string` | Yes | The name of the file to download |
| `mimeType` | `FileMimeType` | Yes | The MIME type of the data to download |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |



# 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.

<ExampleCode id="setup" component="environment" />

### Usage in iframe and shadow dom

The `EnvironmentProvider` component will automatically detect the current environment and set the correct environment
context. 

## Context

Use the `useEnvironmentContext` hook to access the `RootNode`, `Document`, and `Window`.

<ExampleCode id="usage" component="environment" />

## API Reference

**Component API Reference**

**EnvironmentProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `RootNode | (() => RootNode)` | No |  |



# 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

**Example: basic**

```ripple
import { FocusTrap } from 'ark-ripple/focus-trap';
import { track } from 'ripple';

export component Basic() {
  let disabled = track(true);

  <div class="stack">
    <button
      type="button"
      onClick={() => {
        @disabled = false;
      }}
    >
      {'Start Trap'}
    </button>
    <FocusTrap returnFocusOnDeactivate={false} {disabled}>
      <div class="stack">
        <input type="text" placeholder="input" />
        <textarea placeholder="textarea" />
        <button
          type="button"
          onClick={() => {
            @disabled = true;
          }}
        >
          {'End Trap'}
        </button>
      </div>
    </FocusTrap>
  </div>
}

```

### Autofocus

The focus trap respects elements with the `autofocus` attribute.

**Example: autofocus**

```ripple
import { FocusTrap } from 'ark-ripple/focus-trap';
import { track } from 'ripple';

export component Autofocus() {
  let disabled = track(true);
  let buttonRef = track<HTMLButtonElement | null>(null);

  const getButtonNode = () => {
    const node = @buttonRef;
    if (!node) throw new Error('Button not found');
    return node;
  };

  <div class="stack">
    <button
      type="button"
      onClick={() => {
        @disabled = !@disabled;
      }}
      {ref (el: HTMLButtonElement | null) => {
        @buttonRef = el;
      }}
    >
      {@disabled ? 'Start Trap' : 'End Trap'}
    </button>
    if (@disabled) {
      <FocusTrap {disabled} setReturnFocus={getButtonNode}>
        <div class="stack">
          <input type="text" placeholder="Regular input" />
          <input type="text" placeholder="Autofocused input" autofocus />
          <button
            type="button"
            onClick={() => {
              @disabled = true;
            }}
          >
            {'End Trap'}
          </button>
        </div>
      </FocusTrap>
    }
  </div>
}

```

### Initial Focus

Use the `initialFocus` prop to set the element that should receive initial focus when the trap is activated.

**Example: initial-focus**

```ripple
import { FocusTrap } from 'ark-ripple/focus-trap';
import { track } from 'ripple';

export component InitialFocus() {
  let disabled = track(true);
  let inputRef = track<HTMLInputElement | null>(null);

  <div class="stack">
    <button
      type="button"
      onClick={() => {
        @disabled = !@disabled;
      }}
    >
      {@disabled ? 'Start Trap' : 'End Trap'}
    </button>
    <FocusTrap {disabled} initialFocus={() => @inputRef}>
      <div class="stack">
        <input type="text" placeholder="First input" />
        <input
          type="text"
          placeholder="Second input (initial focus)"
          {ref (el: HTMLInputElement | null) => {
            @inputRef = el;
          }}
        />
        <textarea placeholder="textarea" />
        <button
          type="button"
          onClick={() => {
            @disabled = true;
          }}
        >
          {'End Trap'}
        </button>
      </div>
    </FocusTrap>
  </div>
}

```

## API Reference

**Component API Reference**

**FocusTrap Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `disabled` | `boolean` | No | Whether the focus trap is disabled. |
| `fallbackFocus` | `FocusTarget` | No | By default, an error will be thrown if the focus trap contains no
elements in its tab order. With this option you can specify a
fallback element to programmatically receive focus if no other
tabbable elements are found. For example, you may want a popover's
`<div>` to receive focus if the popover's content includes no
tabbable elements. *Make sure the fallback element has a negative
`tabindex` so it can be programmatically focused.

NOTE: If `initialFocus` is `false` (or a function that returns `false`),
this function will not be called when the trap is activated, and no element
will be initially focused. This function may still be called while the trap
is active if things change such that there are no longer any tabbable nodes
in the trap. |
| `initialFocus` | `VoidFunction | FocusTargetOrFalse` | No | By default, when a focus trap is activated the first element in the
focus trap's tab order will receive focus. With this option you can
specify a different element to receive that initial focus, or use `false`
for no initially focused element at all.

NOTE: Setting this option to `false` (or a function that returns `false`)
will prevent the `fallbackFocus` option from being used.

Setting this option to `undefined` (or a function that returns `undefined`)
will result in the default behavior. |
| `onActivate` | `VoidFunction` | No | A function that will be called **before** sending focus to the
target element upon activation. |
| `onDeactivate` | `VoidFunction` | No | A function that will be called **before** sending focus to the
trigger element upon deactivation. |
| `returnFocusOnDeactivate` | `boolean` | No | Default: `true`. If `false`, when the trap is deactivated,
focus will *not* return to the element that had focus before activation. |
| `setReturnFocus` | `type ONLY_FOR_FORMAT =
  | FocusTargetValueOrFalse
  | ((nodeFocusedBeforeActivation: HTMLElement | SVGElement) => FocusTargetValueOrFalse)` | No | By default, focus trap on deactivation will return to the element
that was focused before activation. |



# 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-ripple/format'
```

## Examples

### Basic

Use the `Format.Byte` component to format a byte value with default options.

```ripple
import { Format } from 'ark-ripple/format';
import styles from 'styles/format.module.css';

export component ByteBasic() {
  <div class={styles.Root}>
    <span class={styles.Label}>{'File size'}</span>
    <span class={styles.Value}>
      <Format.Byte value={120000} />
    </span>
  </div>
}
```

### Sizes

Use the `sizes` prop to specify custom byte sizes for formatting.

```ripple
import { Format } from 'ark-ripple/format';
import styles from 'styles/format.module.css';

const byteSizes = [50, 5000, 5000000, 5000000000];

export component ByteSizes() {
  <div class={styles.List}>
    for (const size of byteSizes; key size) {
      <div class={styles.ListItem}>
        <span class={styles.Value}>
          <Format.Byte value={size} />
        </span>
      </div>
    }
  </div>
}
```

### Locale

Use the `locale` prop to format the byte value according to a specific locale.

```ripple
import { Format } from 'ark-ripple/format';
import { LocaleProvider } from 'ark-ripple/locale';
import styles from 'styles/format.module.css';

const locales = ['de-DE', 'zh-CN'];

export component ByteWithLocale() {
  <div class={styles.List}>
    for (const locale of locales; key locale) {
      <LocaleProvider {locale}>
        <div class={styles.ListItem}>
          <span class={styles.InlineLabel}>
            {locale}
            {':'}
          </span>
          <span class={styles.Value}>
            <Format.Byte value={1450.45} />
          </span>
        </div>
      </LocaleProvider>
    }
  </div>
}
```

### Unit

Use the `unit` prop to specify the unit of the byte value.

```ripple
import { Format } from 'ark-ripple/format';
import styles from 'styles/format.module.css';

export component ByteWithUnit() {
  <div class={styles.Inline}>
    <span class={styles.InlineLabel}>{'File size:'}</span>
    <span class={styles.InlineValue}>
      <Format.Byte value={1450.45} unit="bit" />
    </span>
  </div>
}
```

### Unit Display

Use the `unitDisplay` prop to specify the display of the unit.

```ripple
import { Format } from 'ark-ripple/format';
import styles from 'styles/format.module.css';

const unitDisplays = ['narrow', 'short', 'long'] as const;

export component ByteWithUnitDisplay() {
  <div class={styles.List}>
    for (const unitDisplay of unitDisplays; key unitDisplay) {
      <div class={styles.ListItem}>
        <span class={styles.InlineLabel}>
          {unitDisplay}
          {':'}
        </span>
        <span class={styles.Value}>
          <Format.Byte value={50345.53} {unitDisplay} />
        </span>
      </div>
    }
  </div>
}
```

### Unit System

Use the `unitSystem` prop to specify whether to use decimal (1000 bytes) or binary (1024 bytes) unit system.

```ripple
import { Format } from 'ark-ripple/format';
import styles from 'styles/format.module.css';

export component ByteWithUnitSystem() {
  <div class={styles.List}>
    <div class={styles.ListItem}>
      <span class={styles.InlineLabel}>{'Decimal (1000 bytes):'}</span>
      <span class={styles.InlineValue}>
        <Format.Byte value={1024} unitSystem="decimal" />
      </span>
    </div>
    <div class={styles.ListItem}>
      <span class={styles.InlineLabel}>{'Binary (1024 bytes):'}</span>
      <span class={styles.InlineValue}>
        <Format.Byte value={1024} unitSystem="binary" />
      </span>
    </div>
  </div>
}
```


# Format Time 



## Usage

The time formatting logic supports both string (`HH:mm[:ss]`) and `Date` inputs.

```jsx
import { Format } from 'ark-ripple/format'
```

## Examples

### Basic

Use the `Format.Time` component to format a time value with default options.

```ripple
import { Format } from 'ark-ripple/format';
import styles from 'styles/format.module.css';

export component TimeBasic() {
  <span class={styles.Value}>
    <Format.Time value="18:47:12" format="12h" />
  </span>
}
```

### Date

Use a `Date` object as the `value`.

```ripple
import { Format } from 'ark-ripple/format';
import styles from 'styles/format.module.css';

export component TimeWithDate() {
  <div class={styles.Inline}>
    <span class={styles.InlineLabel}>{'Boarding'}</span>
    <span class={styles.InlineValue}>
      <Format.Time value={new Date(2026, 1, 27, 18, 45, 34)} />
    </span>
  </div>
}
```

### Seconds

Use the `withSeconds` prop to include seconds in the output.

```ripple
import { Format } from 'ark-ripple/format';
import styles from 'styles/format.module.css';

export component TimeWithSeconds() {
  <div class={styles.Inline}>
    <span class={styles.InlineLabel}>{'Boarding'}</span>
    <span class={styles.InlineValue}>
      <Format.Time value="03:07:19" format="12h" withSeconds />
    </span>
  </div>
}
```

### AM/PM Labels

Use `amPmLabels` to customize day-period labels when using 12-hour format.

```ripple
import { Format } from 'ark-ripple/format';
import styles from 'styles/format.module.css';

export component TimeWithAmPmLabels() {
  <div class={styles.Inline}>
    <span class={styles.InlineLabel}>{'Boarding'}</span>
    <span class={styles.InlineValue}>
      <Format.Time value={new Date(2026, 1, 27, 18, 45, 34)} />
    </span>
  </div>
}
```

### Locale

Use the locale provider to format the time according to a specific locale.

```ripple
import { Format } from 'ark-ripple/format';
import { LocaleProvider } from 'ark-ripple/locale';
import styles from 'styles/format.module.css';

export component TimeWithLocale() {
  <LocaleProvider locale="ar-EG">
    <span class={styles.Value}>
      <Format.Time value="13:05" format="12h" />
    </span>
  </LocaleProvider>
}
```


# Format Relative Time 



## Usage

The relative time formatting logic is handled by the native `Intl.RelativeTimeFormat` API and smartly cached to avoid
performance issues when using the same locale and options.

```jsx
import { Format } from 'ark-ripple/format'
```

## Examples

### Basic

Use the `Format.RelativeTime` component to format a relative time with default options.

```ripple
import { Format } from 'ark-ripple/format';
import styles from 'styles/format.module.css';

export component RelativeTimeBasic() {
  <div class={styles.Inline}>
    <span class={styles.InlineLabel}>{'Last updated'}</span>
    <span class={styles.InlineValue}>
      <Format.RelativeTime value={new Date('2025-05-05')} />
    </span>
  </div>
}
```

### Short

Use the `style="short"` prop to format the relative time in short format.

```ripple
import { Format } from 'ark-ripple/format';
import styles from 'styles/format.module.css';

export component RelativeTimeShort() {
  <div class={styles.Inline}>
    <span class={styles.InlineLabel}>{'Edited'}</span>
    <span class={styles.InlineValue}>
      <Format.RelativeTime value={new Date('2025-05-05')} style="short" />
    </span>
  </div>
}
```


# 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-ripple/frame'
```

## Examples

### Basic

Wrap your component in the `Frame` component to render it in an iframe.

```ripple
import { Frame } from 'ark-ripple/frame';

export component Basic() {
  <Frame
    title="Custom Frame"
    style={{ border: '1px solid #ccc', width: '100%', height: 'var(--height)' }}
  >
    component head() {
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <style raw>
        body {
          background-color: red;
        }
      </style>
    }
    <div style="padding: 40px">
      <h1>{'Hello from inside the frame!'}</h1>
      <p>{'This content is rendered within our custom frame component using a Portal.'}</p>
    </div>
  </Frame>
}
```

### Injecting Script

Using the `onMount` prop, you can inject a script into the iframe.

```ripple
import { Frame } from 'ark-ripple/frame';
import { track } from 'ripple';

export component Script() {
  const frameRef = track<HTMLIFrameElement | null>(null);

  <Frame
    title="Custom Frame"
    {ref (el: HTMLIFrameElement) => {
      @frameRef = el;
    }}
    onMount={() => {
      const doc = @frameRef?.contentDocument;
      if (!doc) return;
      const script = doc.createElement('script');
      script.innerHTML = 'console.log("Hello from inside the frame!")';
      doc.body.appendChild(script);
    }}
    style={{ border: '1px solid #ccc', width: '100%', height: 'var(--height)' }}
  >
    <div style={{ padding: '40px' }}>
      <h1>{'Hello from inside the frame!'}</h1>
      <p>{'This content is rendered within our custom frame component using a Portal.'}</p>
    </div>
  </Frame>
}
```

### Custom src doc

Use the `srcDoc` prop to specify the HTML content of the page to use in the iframe.

```ripple
import { Frame } from 'ark-ripple/frame';

const srcDoc = `<html><head>
<link href="//use.fontawesome.com/releases/v5.15.1/css/all.css" rel="stylesheet" />
<link href="//fonts.googleapis.com/css?family=Open+Sans:400,300,600,700" rel="stylesheet" type="text/css" />
<base target=_blank>
</head><body style='overflow: hidden'><div></div></body></html>`;

export component SrcDoc() {
  <Frame
    title="Custom Frame"
    style={{ border: '1px solid #ccc', maxWidth: '800px', width: '100%' }}
    {srcDoc}
  >
    <h1 style={{ fontFamily: 'Open Sans, sans-serif' }}>{'Hello from inside the frame!'}</h1>
    <p>{'This content is rendered within our custom frame component using a Portal.'}</p>
    <p>{'The frame has custom initial content, including Font Awesome and Open Sans font.'}</p>
  </Frame>
}
```

## API Reference

### Props

**Component API Reference**

**Frame Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `head` | `string | number | bigint | boolean | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...>` | No | Additional content to be inserted into the frame's <head> |
| `onMount` | `() => void` | No | Callback function to be executed when the frame is mounted |
| `onUnmount` | `() => void` | No | Callback function to be executed when the frame is unmounted |



# 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 `<mark>` tags.

**Example: basic**

```ripple
import { Highlight } from 'ark-ripple/highlight';
import styles from 'styles/highlight.module.css';

export component Basic() {
  <p class={styles.Text}>
    <Highlight
      class={styles.Mark}
      query="component"
      text="Ark UI is a headless component library for building accessible web applications."
    />
  </p>
}

```

### Dynamic Query

Control the `query` prop with state to create an interactive search highlighting experience.

**Example: dynamic-query**

```ripple
import { Highlight } from 'ark-ripple/highlight';
import { track } from 'ripple';
import field from 'styles/field.module.css';
import styles from 'styles/highlight.module.css';

export component DynamicQuery() {
  const query = track('component');

  <div class={styles.Root}>
    <input
      class={field.Input}
      type="text"
      placeholder="Search text..."
      value={@query}
      onInput={(e) => {
        @query = (e.target as HTMLInputElement).value;
      }}
    />
    <p class={styles.Text}>
      <Highlight
        class={styles.Mark}
        {query}
        text="With Ark UI, you can build accessible, custom components. Each component is fully typed and works seamlessly with React, Solid, Svelte, and Vue."
      />
    </p>
  </div>
}

```

### Multiple Queries

You can highlight multiple terms by passing an array of strings to the `query` prop.

**Example: multiple**

```ripple
import { Highlight } from 'ark-ripple/highlight';
import styles from 'styles/highlight.module.css';

export component Multiple() {
  <p class={styles.Text}>
    <Highlight
      class={styles.Mark}
      query={['React', 'Vue']}
      text="Ark UI provides React, Solid, Vue, and Svelte components that are accessible and customizable."
    />
  </p>
}

```

### Case Sensitivity

By default, the highlighting is case-sensitive. Use the `ignoreCase` prop to make it case-insensitive.

**Example: ignore-case**

```ripple
import { Highlight } from 'ark-ripple/highlight';
import styles from 'styles/highlight.module.css';

export component IgnoreCase() {
  <p class={styles.Text}>
    <Highlight
      class={styles.Mark}
      text="TypeScript provides static type checking. Using typescript helps catch errors early in development."
      query="typescript"
      ignoreCase
    />
  </p>
}

```

### Match All

By default, the Highlight component matches the first occurrence of the query. To highlight all occurrences of the
query, set the `matchAll` prop to `true`.

**Example: match-all**

```ripple
import { Highlight } from 'ark-ripple/highlight';
import styles from 'styles/highlight.module.css';

export component MatchAll() {
  <div class={styles.Root}>
    <div class={styles.Section}>
      <span class={styles.Label}>{'Match All'}</span>
      <p class={styles.Text}>
        <Highlight
          class={styles.Mark}
          text="Each component follows WAI-ARIA guidelines. Every component is rigorously tested to ensure accessibility."
          query="component"
          matchAll
        />
      </p>
    </div>
    <div class={styles.Section}>
      <span class={styles.Label}>{'Match First Only'}</span>
      <p class={styles.Text}>
        <Highlight
          class={styles.Mark}
          text="Each component follows WAI-ARIA guidelines. Every component is rigorously tested to ensure accessibility."
          query="component"
          matchAll={false}
        />
      </p>
    </div>
  </div>
}

```

### Exact Match

By default, the Highlight component matches partial words. Use the `exactMatch` prop to only highlight whole words that
match the query exactly.

**Example: exact-match**

```ripple
import { Highlight } from 'ark-ripple/highlight';
import styles from 'styles/highlight.module.css';

export component ExactMatch() {
  <div class={styles.Root}>
    <div class={styles.Section}>
      <span class={styles.Label}>{'Partial Match'}</span>
      <p class={styles.Text}>
        <Highlight
          class={styles.Mark}
          query="box"
          text="The checkbox component renders a box element. Use combobox for autocomplete."
          matchAll
        />
      </p>
    </div>
    <div class={styles.Section}>
      <span class={styles.Label}>{'Exact Match'}</span>
      <p class={styles.Text}>
        <Highlight
          class={styles.Mark}
          query="box"
          text="The checkbox component renders a box element. Use combobox for autocomplete."
          exactMatch
          matchAll
        />
      </p>
    </div>
  </div>
}

```

## API Reference

**Component API Reference**

**Highlight Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `query` | `string | string[]` | Yes | The query to highlight in the text |
| `text` | `string` | Yes | The text to highlight |
| `exactMatch` | `boolean` | No | Whether to match whole words only |
| `ignoreCase` | `boolean` | No | Whether to ignore case while matching |
| `matchAll` | `boolean` | No | Whether to match multiple instances of the query |


## Customization

The Highlight component wraps matched text in `<mark>` tags. Pass a `className` (or `class` in Solid/Svelte/Vue) to
style the highlighted portions.

```tsx
<Highlight
  text="Ark UI is a headless component library for building accessible web applications."
  query="component"
  className="highlight-mark"
/>
```

Style the `mark` tags using CSS to customize the appearance of highlighted text.

```css
.highlight-mark {
  background-color: #ffe5e4;
  color: #c9453b;
  border-radius: 0.125rem;
}
```


# JSON Tree View 



## Anatomy

To set up the JSON tree view correctly, you'll need to understand its anatomy and how we name its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Examples

Learn how to use the `JsonTreeView` component in your project. Let's take a look at the most basic example:

**Example: basic**

```ripple
import { JsonTreeView } from 'ark-ripple/json-tree-view';
import { ChevronRight } from 'lucide-ripple';
import styles from 'styles/json-tree-view.module.css';

export component Basic() {
  <JsonTreeView.Root
    defaultExpandedDepth={1}
    class={styles.Root}
    data={{
      name: 'John Doe',
      age: 30,
      email: 'john.doe@example.com',
      tags: ['tag1', 'tag2', 'tag3'],
      address: {
        street: '123 Main St',
        city: 'Anytown',
        state: 'CA',
        zip: '12345',
      },
    }}
  >
    <JsonTreeView.Tree class={styles.Tree} arrow={ChevronRight} />
  </JsonTreeView.Root>
}

```

### Different Data Types

The JSON tree view can display various JavaScript data types including objects, arrays, primitives, and special values:

**Example: array-data**

```ripple
import { JsonTreeView } from 'ark-ripple/json-tree-view';
import { ChevronRight } from 'lucide-ripple';
import styles from 'styles/json-tree-view.module.css';

const testArray = [1, 2, 3, 4, 5];
Object.defineProperties(testArray, {
  customProperty: { value: 'custom value', enumerable: false, writable: false },
  anotherProperty: { value: 42, enumerable: false, writable: false },
});

const getSparseArray = () => {
  const sparse: any[] = [];
  sparse[0] = 'first';
  sparse[5] = 'sixth';
  return sparse;
};

export component ArrayData() {
  <JsonTreeView.Root
    defaultExpandedDepth={1}
    class={styles.Root}
    data={{
      normalArray: [1, 2, 3],
      arrayWithNonEnumerableProperties: testArray,
      sparseArray: getSparseArray(),
    }}
  >
    <JsonTreeView.Tree class={styles.Tree} arrow={ChevronRight} />
  </JsonTreeView.Root>
}

```

### Functions and Methods

Display JavaScript functions, async functions, and generators in your JSON tree:

**Example: functions**

```ripple
import { JsonTreeView } from 'ark-ripple/json-tree-view';
import { ChevronRight } from 'lucide-ripple';
import styles from 'styles/json-tree-view.module.css';

const data = [
  function sum(a: number, b: number) {
    return a + b;
  },
  async (promises: Promise<any>[]) => await Promise.all(promises),
  function* generator(a: number) {
    while (a > 0) {
      yield a - 1;
    }
  },
];

export component Functions() {
  <JsonTreeView.Root defaultExpandedDepth={1} class={styles.Root} {data}>
    <JsonTreeView.Tree class={styles.Tree} arrow={ChevronRight} />
  </JsonTreeView.Root>
}

```

### Regular Expressions

Regular expressions are displayed with their pattern and flags:

**Example: regex**

```ripple
import { JsonTreeView } from 'ark-ripple/json-tree-view';
import { ChevronRight } from 'lucide-ripple';
import styles from 'styles/json-tree-view.module.css';

const data = {
  regex: /^[a-z0-9]+/g,
  case_insensitive: /^(?:[a-z0-9]+)foo.*?/i,
};

export component Regex() {
  <JsonTreeView.Root defaultExpandedDepth={1} class={styles.Root} {data}>
    <JsonTreeView.Tree class={styles.Tree} arrow={ChevronRight} />
  </JsonTreeView.Root>
}

```

### Error Objects

Error objects and their stack traces can be visualized:

**Example: errors**

```ripple
import { JsonTreeView } from 'ark-ripple/json-tree-view';
import { ChevronRight } from 'lucide-ripple';
import styles from 'styles/json-tree-view.module.css';

const data = new Error('Error');

export component Errors() {
  <JsonTreeView.Root class={styles.Root} {data} defaultExpandedDepth={1}>
    <JsonTreeView.Tree class={styles.Tree} arrow={ChevronRight} />
  </JsonTreeView.Root>
}

```

### Map and Set Objects

Native JavaScript Map and Set objects are supported:

**Example: map-and-set**

```ripple
import { JsonTreeView } from 'ark-ripple/json-tree-view';
import { ChevronRight } from 'lucide-ripple';
import styles from 'styles/json-tree-view.module.css';

const data = new Map<string, any>([
  ['name', 'ark-ui-json-tree'],
  ['license', 'MIT'],
  ['elements', new Set(['ark-ui', 123, false, true, null, undefined, 456n])],
  [
    'nested',
    new Map<string, any>([
      [
        'taglines',
        new Set([
          { name: 'ark-ui', feature: 'headless components' },
          { name: 'ark-ui', feature: 'framework agnostic' },
          { name: 'ark-ui', feature: 'accessible by default' },
        ]),
      ],
    ]),
  ],
]);

export component MapAndSet() {
  <JsonTreeView.Root defaultExpandedDepth={1} class={styles.Root} {data}>
    <JsonTreeView.Tree class={styles.Tree} arrow={ChevronRight} />
  </JsonTreeView.Root>
}

```

### Controlling Expand Level

Use the `defaultExpandedDepth` prop to control how many levels are expanded by default:

**Example: expand-level**

```ripple
import { JsonTreeView } from 'ark-ripple/json-tree-view';
import { ChevronRight } from 'lucide-ripple';
import styles from 'styles/json-tree-view.module.css';

export component ExpandLevel() {
  <JsonTreeView.Root
    class={styles.Root}
    defaultExpandedDepth={2}
    data={{
      name: 'John Doe',
      age: 30,
      email: 'john.doe@example.com',
      tags: ['tag1', 'tag2', 'tag3'],
      address: {
        street: '123 Main St',
        city: 'Anytown',
        state: 'CA',
        zip: '12345',
      },
    }}
  >
    <JsonTreeView.Tree class={styles.Tree} arrow={ChevronRight} />
  </JsonTreeView.Root>
}

```

### Custom Value Rendering

You can customize how specific values are rendered using the `renderValue` prop. This example shows how to make email
addresses clickable:

**Example: render-value**

```ripple
import { JsonTreeView } from 'ark-ripple/json-tree-view';
import type { JsonNodeHastElement } from '@zag-js/json-tree-utils';
import { ChevronRight } from 'lucide-ripple';
import styles from 'styles/json-tree-view.module.css';

export component RenderValue() {
  <JsonTreeView.Root
    class={styles.Root}
    defaultExpandedDepth={2}
    data={{
      name: 'John Doe',
      age: 30,
      number: Number.NaN,
      email: 'john.doe@example.com',
      address: {
        street: '123 Main St',
        city: 'Anytown',
        state: 'CA',
        zip: '12345',
      },
    }}
  >
    <JsonTreeView.Tree class={styles.Tree} arrow={ChevronRight}>
      component renderValue({ node }) {
        if (@node.type === 'text' && typeof @node.value === 'string' && isEmail(@node.value)) {
          const email = @node.value.replace(/^"(.*)"$/, '$1');
          <a href={`mailto:${email}`} target="_blank" rel="noreferrer">{email}</a>
        } else {
          {@node.value}
        }
      }
    </JsonTreeView.Tree>
  </JsonTreeView.Root>
}

const isEmail = (value: string) => {
  const strippedValue = value.replace(/^"(.*)"$/, '$1');
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(strippedValue);
};

```

### Configuration Options

The JSON tree view supports several configuration options to customize the display:

```tsx
<JsonTreeView.Root
  data={data}
  defaultExpandedDepth={2}
  quotesOnKeys={true}
  showNonenumerable={true}
  maxPreviewItems={5}
  collapseStringsAfterLength={50}
  groupArraysAfterLength={100}
>
  <JsonTreeView.Tree arrow={<ChevronRightIcon />} />
</JsonTreeView.Root>
```

**Configuration Options:**

- **`quotesOnKeys`**: Whether to show quotes around object keys
- **`showNonenumerable`**: Whether to show non-enumerable properties
- **`maxPreviewItems`**: Maximum number of items to show in object/array previews
- **`collapseStringsAfterLength`**: Collapse strings longer than this length
- **`groupArraysAfterLength`**: Group array items when array is longer than this length

### Using the Root Provider

The `RootProvider` component provides a context for the JSON tree view. It accepts the value of the `useJsonTreeView`
hook. You can leverage it to access the component state and methods from outside the JSON tree view.

**Example: root-provider**

```ripple
import { JsonTreeView, useJsonTreeView } from 'ark-ripple/json-tree-view';
import { ChevronRight } from 'lucide-ripple';
import styles from 'styles/json-tree-view.module.css';

export component RootProvider() {
  const jsonTreeView = useJsonTreeView(
    {
      defaultExpandedDepth: 1,
      data: {
        name: 'John Doe',
        age: 30,
        email: 'john.doe@example.com',
        tags: ['tag1', 'tag2', 'tag3'],
        address: {
          street: '123 Main St',
          city: 'Anytown',
          state: 'CA',
          zip: '12345',
        },
      },
    },
  );

  <JsonTreeView.RootProvider class={styles.Root} value={jsonTreeView}>
    <JsonTreeView.Tree class={styles.Tree} arrow={ChevronRight} />
  </JsonTreeView.RootProvider>
}

```

> If you're using the `RootProvider` component, you don't need to use the `Root` component.

## API Reference

**Component API Reference**

**JsonTreeViewRoot Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `canRename` | `(node: JsonNode<any>, indexPath: IndexPath) => boolean` | No | Function to determine if a node can be renamed |
| `checkedValue` | `string[]` | No | The controlled checked node value |
| `collapseStringsAfterLength` | `number` | No |  |
| `data` | `{}` | No | The data to display in the tree. |
| `defaultCheckedValue` | `string[]` | No | The initial checked node value when rendered.
Use when you don't need to control the checked node value. |
| `defaultExpandedDepth` | `number` | No | The default expand level. |
| `defaultExpandedValue` | `string[]` | No | The initial expanded node ids when rendered.
Use when you don't need to control the expanded node value. |
| `defaultFocusedValue` | `string` | No | The initial focused node value when rendered.
Use when you don't need to control the focused node value. |
| `defaultSelectedValue` | `string[]` | No | The initial selected node value when rendered.
Use when you don't need to control the selected node value. |
| `expandedValue` | `string[]` | No | The controlled expanded node ids |
| `expandOnClick` | `boolean` | No | Whether clicking on a branch should open it or not |
| `focusedValue` | `string` | No | The value of the focused node |
| `groupArraysAfterLength` | `number` | No |  |
| `ids` | `Partial<{ root: string; tree: string; label: string; node: (value: string) => string }>` | No | The ids of the tree elements. Useful for composition. |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `loadChildren` | `(details: LoadChildrenDetails<JsonNode<any>>) => Promise<JsonNode<any>[]>` | No | Function to load children for a node asynchronously.
When provided, branches will wait for this promise to resolve before expanding. |
| `maxPreviewItems` | `number` | No |  |
| `onBeforeRename` | `(details: RenameCompleteDetails) => boolean` | No | Called before a rename is completed. Return false to prevent the rename. |
| `onCheckedChange` | `(details: CheckedChangeDetails) => void` | No | Called when the checked value changes |
| `onExpandedChange` | `(details: ExpandedChangeDetails<JsonNode<any>>) => void` | No | Called when the tree is opened or closed |
| `onFocusChange` | `(details: FocusChangeDetails<JsonNode<any>>) => void` | No | Called when the focused node changes |
| `onLoadChildrenComplete` | `(details: LoadChildrenCompleteDetails<JsonNode<any>>) => void` | No | Called when a node finishes loading children |
| `onLoadChildrenError` | `(details: LoadChildrenErrorDetails<JsonNode<any>>) => void` | No | Called when loading children fails for one or more nodes |
| `onRenameComplete` | `(details: RenameCompleteDetails) => void` | No | Called when a node label rename is completed |
| `onRenameStart` | `(details: RenameStartDetails<JsonNode<any>>) => void` | No | Called when a node starts being renamed |
| `onSelectionChange` | `(details: SelectionChangeDetails<JsonNode<any>>) => void` | No | Called when the selection changes |
| `quotesOnKeys` | `boolean` | No | Whether to show quotes on the keys. |
| `scrollToIndexFn` | `(details: ScrollToIndexDetails<JsonNode<any>>) => void` | No | Function to scroll to a specific index.
Useful for virtualized tree views. |
| `selectedValue` | `string[]` | No | The controlled selected node value |
| `selectionMode` | `'single' | 'multiple'` | No | Whether the tree supports multiple selection
- "single": only one node can be selected
- "multiple": multiple nodes can be selected |
| `showNonenumerable` | `boolean` | No |  |
| `typeahead` | `boolean` | No | Whether the tree supports typeahead search |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


**JsonTreeViewRootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseJsonTreeViewReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


**JsonTreeViewTree Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `arrow` | `ReactElement<unknown, string | JSXElementConstructor<any>>` | No | The icon to use for the arrow. |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `indentGuide` | `boolean | ReactElement<unknown, string | JSXElementConstructor<any>>` | No | The indent guide to use for the tree. |
| `renderValue` | `(node: JsonNodeHastElement) => ReactNode` | No | The function to render the value of the node. |


## Accessibility

The JSON tree view is built on top of the Tree View component and 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.<br> 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.<br> When focus is on an item or branch node, moves focus to its parent branch node.

**`Home`**
Description: Moves focus to first node without opening or closing a node.

**`End`**
Description: Moves focus to the last node that can be focused without expanding any nodes that are closed.

**`a-z + A-Z`**
Description: Focus moves to the next node with a name that starts with the typed character. The search logic ignores nodes that are descendants of closed branch.

**`*`**
Description: Expands all sibling nodes that are at the same depth as the focused node.

**`Shift + ArrowDown`**
Description: Moves focus to and toggles the selection state of the next node.

**`Shift + ArrowUp`**
Description: Moves focus to and toggles the selection state of the previous node.

**`Ctrl + A`**
Description: Selects all nodes in the tree. If all nodes are selected, unselects all nodes.


# Locale 

## Setup

The `LocaleProvider` component sets the locale for your app, formatting dates, numbers, and other locale-specific data.

> **Note:** If no `LocaleProvider` is setup, the default locale for the app will be `en-US` and therefore the direction
> will be `ltr`.

<ExampleCode id="setup" component="locale" />

## Usage

To access the current locale and direction settings, use the `useLocaleContext` hook.

<ExampleCode id="usage" component="locale" />

## API Reference

**Component API Reference**

**LocaleProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `locale` | `string` | Yes | The locale to use for the application. |



# Presence 

## Examples

By default the child component starts out as hidden and remains hidden after the `present` state is toggled off. This is
useful for situations where the element needs to be hidden initially and continue to stay hidden after its presence is
no longer required.

**Example: basic**

```ripple
import { track } from 'ripple';
import { Presence } from 'ark-ripple/presence';
import button from 'styles/button.module.css';
import styles from 'styles/presence.module.css';

export component Basic() {
  let present = track(false);

  <div class="stack">
    <button
      class={button.Root}
      onClick={() => {
        @present = !@present;
      }}
    >
      {'Toggle'}
    </button>
    <Presence class={styles.Box} {present}>{'Content'}</Presence>
  </div>
}

```

### Lazy Mount

To delay the mounting of a child component until the `present` prop is set to true, use the `lazyMount` prop:

**Example: lazy-mount**

```ripple
import { track } from 'ripple';
import { Presence } from 'ark-ripple/presence';
import button from 'styles/button.module.css';
import styles from 'styles/presence.module.css';

export component LazyMount() {
  let present = track(false);

  <div class="stack">
    <button
      class={button.Root}
      onClick={() => {
        @present = !@present;
      }}
    >
      {'Toggle'}
    </button>
    <Presence class={styles.Box} lazyMount {present}>{'Lazy Mounted'}</Presence>
  </div>
}

```

### Unmount on Exit

To remove the child component from the DOM when it's not present, use the `unmountOnExit` prop:

**Example: unmount-on-exit**

```ripple
import { track } from 'ripple';
import { Presence } from 'ark-ripple/presence';
import button from 'styles/button.module.css';
import styles from 'styles/presence.module.css';

export component UnmountOnExit() {
  let present = track(false);

  <div class="stack">
    <button
      class={button.Root}
      onClick={() => {
        @present = !@present;
      }}
    >
      {'Toggle'}
    </button>
    <Presence class={styles.Box} unmountOnExit {present}>{'Unmount on Exit'}</Presence>
  </div>
}

```

### 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:

**Example: lazy-mount-and-unmount-on-exit**

```ripple
import { track } from 'ripple';
import { Presence } from 'ark-ripple/presence';
import button from 'styles/button.module.css';
import styles from 'styles/presence.module.css';

export component LazyMountAndUnmountOnExit() {
  let present = track(false);

  <div class="stack">
    <button
      class={button.Root}
      onClick={() => {
        @present = !@present;
      }}
    >
      {'Toggle'}
    </button>
    <Presence class={styles.Box} lazyMount unmountOnExit {present}>{'Lazy + Unmount'}</Presence>
  </div>
}

```

## API Reference

**Component API Reference**

**Presence Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state |
| `present` | `boolean` | No | Whether the node is present (controlled by the user) |
| `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |



# Swap 



## Anatomy



```tsx
<Swap.Root>
  <Swap.Indicator />
</Swap.Root>
```

## Examples

### Fade

Swap between two icons with a fade animation. Set the `swap` prop to toggle between the `on` and `off` indicators.

**Example: fade**

```ripple
import { Swap } from 'ark-ripple/swap';
import { Check, X } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/swap.module.css';

export component Fade() {
  let swapped = track(false);

  <button
    type="button"
    class={styles.Button}
    onClick={() => {
      @swapped = !@swapped;
    }}
  >
    <Swap.Root swap={swapped}>
      <Swap.Indicator type="on" class={styles.FadeIndicator}>
        <Check />
      </Swap.Indicator>
      <Swap.Indicator type="off" class={styles.FadeIndicator}>
        <X />
      </Swap.Indicator>
    </Swap.Root>
  </button>
}

```

### Flip

Add a 3D flip effect by setting `perspective` on the root and using `rotateY` keyframes on the indicators.

**Example: flip**

```ripple
import { Swap } from 'ark-ripple/swap';
import { Pause, Play } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/swap.module.css';

export component Flip() {
  let swapped = track(false);

  <button
    type="button"
    class={styles.Button}
    onClick={() => {
      @swapped = !@swapped;
    }}
  >
    <Swap.Root swap={swapped} style={{ perspective: '200px' }}>
      <Swap.Indicator type="on" class={styles.FlipIndicator}>
        <Play />
      </Swap.Indicator>
      <Swap.Indicator type="off" class={styles.FlipIndicator}>
        <Pause />
      </Swap.Indicator>
    </Swap.Root>
  </button>
}

```

### Rotate

Rotate the indicators in and out with a spin transition.

**Example: rotate**

```ripple
import { Swap } from 'ark-ripple/swap';
import { Moon, Sun } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/swap.module.css';

export component Rotate() {
  let swapped = track(false);

  <button
    type="button"
    class={styles.Button}
    onClick={() => {
      @swapped = !@swapped;
    }}
  >
    <Swap.Root swap={swapped}>
      <Swap.Indicator type="on" class={styles.RotateIndicator}>
        <Sun />
      </Swap.Indicator>
      <Swap.Indicator type="off" class={styles.RotateIndicator}>
        <Moon />
      </Swap.Indicator>
    </Swap.Root>
  </button>
}

```

### Scale

Scale the indicators up and down for a pop-in effect.

**Example: scale**

```ripple
import { Swap } from 'ark-ripple/swap';
import { Volume2, VolumeX } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/swap.module.css';

export component Scale() {
  let swapped = track(false);

  <button
    type="button"
    class={styles.Button}
    onClick={() => {
      @swapped = !@swapped;
    }}
  >
    <Swap.Root swap={swapped}>
      <Swap.Indicator type="on" class={styles.ScaleIndicator}>
        <Volume2 />
      </Swap.Indicator>
      <Swap.Indicator type="off" class={styles.ScaleIndicator}>
        <VolumeX />
      </Swap.Indicator>
    </Swap.Root>
  </button>
}

```

## Guides

### How It Works

Swap renders two indicators stacked on top of each other in a 1x1 CSS grid. The `swap` prop controls which indicator is
visible. Each indicator uses the presence system, so you get `data-state="open"` and `data-state="closed"` attributes to
drive your CSS animations.

### Animating Indicators

Target `data-state` on each indicator to define enter and exit animations:

```css
.indicator[data-state='open'] {
  animation: fade-in 200ms ease-out;
}

.indicator[data-state='closed'] {
  animation: fade-out 100ms ease-in;
}

@keyframes fade-in {
  from {
    opacity: 0;
  }
  to {
    opacity: 1;
  }
}

@keyframes fade-out {
  from {
    opacity: 1;
  }
  to {
    opacity: 0;
  }
}
```

You can combine animations for richer effects. For example, scale with fade:

```css
.indicator[data-state='open'] {
  animation:
    scale-in 200ms ease-out,
    fade-in 200ms ease-out;
}

.indicator[data-state='closed'] {
  animation:
    scale-out 100ms ease-in,
    fade-out 100ms ease-in;
}
```

### 3D Flip Animation

For a flip effect, set `perspective` on the root and use `backface-visibility: hidden` on indicators:

```css
.flip-indicator {
  backface-visibility: hidden;
}

.flip-indicator[data-state='open'] {
  animation: flip-in 400ms ease;
}

.flip-indicator[data-state='closed'] {
  animation: flip-out 200ms ease;
}

@keyframes flip-in {
  from {
    transform: rotateY(180deg);
  }
  to {
    transform: rotateY(0deg);
  }
}

@keyframes flip-out {
  from {
    transform: rotateY(0deg);
  }
  to {
    transform: rotateY(180deg);
  }
}
```

### Lazy Mount

Use `lazyMount` and `unmountOnExit` to control when indicators mount and unmount. This keeps the DOM clean when
indicators aren't visible.

```tsx
<Swap.Root swap={@swapped} lazyMount unmountOnExit>
  <Swap.Indicator type="on">...</Swap.Indicator>
  <Swap.Indicator type="off">...</Swap.Indicator>
</Swap.Root>
```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `swap` | `boolean` | No | Whether the swap is in the "on" state. |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


**Indicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `type` | `'on' | 'off'` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseSwapReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


### Context

<ContextType id="swap" />