# Introduction Documentation

The headless components for Svelte.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

Bits UI is a collection of headless component primitives for Svelte that prioritizes developer experience, accessibility, and flexibility. Our vision is to empower developers to build high-quality, accessible user interfaces without sacrificing creative control or performance.

## Why Bits UI?

### Bring Your Own Styles

Most components ship with zero styling. Minimal styles are included only when absolutely necessary for core functionality. You maintain complete control over the visual design, applying your own styles through standard Svelte class props or targeting components via data attributes. See our [styling guide](/docs/styling) for implementation details.

### Empowering DX

Every component is designed with developer experience in mind:

- Extensive TypeScript support  
- Predictable behavior and consistent APIs  
- Comprehensive documentation and examples  
- Flexible event override system for custom behavior  
- Sensible defaults ### Built for Production

- Strives to follow [W3C ARIA Authoring Practices](https://www.w3.org/TR/wai-aria-practices-1.2/)
- Built-in keyboard navigation  
- Screen reader optimization  
- Focus management ### Composable Architecture

Components are designed to work independently or together, featuring:

- [Render Delegation](/docs/child-snippet) for maximum flexibility
- Chainable events and callbacks  
- Override-friendly defaults  
- Minimal dependencies ## Community

Bits UI is an open-source project built and maintained by [Hunter Johnston](https://x.com/huntabyte) with design support from [Pavel Stianko](https://x.com/pavel_stianko) and his team at [Bitworks Studio](https://bitworks.cz). We always welcome contributions and feedback from the community.

Found an accessibility issue or have a suggestion? [Open an issue](https://github.com/huntabyte/bits-ui/issues/new).

## Acknowledgments

Built on the shoulders of giants:

- [Melt UI](https://melt-ui.com) \- Inspired our internal architecture and powered the first version of Bits UI
- [Radix UI](https://radix-ui.com) \- Reference for component API design
- [React Spectrum](https://react-spectrum.adobe.com) \- Inspiration for date/time components

----------------------------------------------------

# Child Snippet Documentation

Learn how to use the `child` snippet to render your own elements.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

## Usage

Many Bits UI components have a default HTML element that wraps their `children`. For example, `Accordion.Trigger` typically renders as:

```svelte
<button>
 {@render children()}
</button>
```

While you can set standard button attributes, you might need more control for:

- Applying Svelte transitions or actions  
- Using custom components  
- Scoped CSS This is where the `child` snippet comes in.

Components supporting render delegation accept an optional child prop, which is a Svelte snippet. When used, the component passes its attributes to this snippet, allowing you to apply them to any element.

Let's take a look at an example using the `Accordion.Trigger` component:

```svelte
<Accordion.Trigger>
 {#snippet child({ props })}
  <div {...props}>Open accordion item</div>
 {/snippet}
</Accordion.Trigger>
```

The `props` object includes event handlers, ARIA attributes, and any other attributes passed to `Accordion.Trigger`. Note that when using `child`, other children outside this snippet are ignored.

## Custom IDs & Attributes

To use custom IDs, event handlers, or other attributes with a custom element, you must pass them to the component first. This is crucial because:

- Many Bits UI internals rely on specific IDs  
- Props are merged using a [`mergeProps`](/docs/utilities/merge-props)
  function to handle cancelling internal handlers, etc.

Correct usage:

```svelte
<Accordion.Trigger id="my-custom-id" onclick={() => console.log("clicked")}>
 {#snippet child({ props })}
  <div {...props}>Open accordion item</div>
 {/snippet}
</Accordion.Trigger>
```

In this example, `my-custom-id`, the click event handler, and my-custom-class are properly merged into the `props` object, ensuring they work alongside Bits UI's internal logic.

Behind the scenes, components using the child prop typically implement logic similar to this:

```svelte
<script lang="ts">
 // other imports/props/logic omitted for brevity
 let { child, children, ...restProps } = $props();
 const trigger = makeTrigger();
 const mergedProps = $derived(mergeProps(restProps, trigger.props));
</script>
{#if child}
 {@render child({ props: mergedProps })}
{:else}
 <button {...mergedProps}>
  {@render children?.()}
 </button>
{/if}
```

## Floating Content Components

Floating content components (tooltips, popovers, dropdowns, etc.) require special handling when used with the `child` snippet due to their positioning requirements with Floating UI.

### Implementation Details

When implementing floating content, you must:

- Include a wrapper element within the `child` snippet
- Spread the `wrapperProps` prop to this wrapper element
- Place your floating content inside this wrapper ```svelte
<Popover.Content>
 {#snippet child({ wrapperProps, props, open })}
  {#if open}
   <div {...wrapperProps}>
    <div {...props}>
    </div>
   </div>
  {/if}
 {/snippet}
</Popover.Content>
```

### Important Considerations

- The wrapper element must remain unstyled as its positioning is managed internally by Floating UI  
- The `wrapperProps` contain computed positioning data essential for proper floating behavior
- Modifying the wrapper element's styles or structure may break positioning calculations ### Affected Components

The following components require a wrapper element:

- `Combobox.Content` - `DatePicker.Content` - `DateRangePicker.Content` - `DropdownMenu.Content` - `LinkPreview.Content` - `Menubar.Content` - `Popover.Content` - `Select.Content` - `Tooltip.Content`

----------------------------------------------------

# Dates and Times Documentation

How to work with the various date and time components in Bits UI.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

The date and time components in Bits UI are built on top of the [`@internationalized/date`](https://react-spectrum.adobe.com/internationalized/date/index.html) package, which provides a unified API for working with dates and times in different locales and time zones. It's heavily inspired by the [Temporal](https://tc39.es/proposal-temporal/) proposal, and intends to back the objects in this package with the Temporal API once it's available.

You can install the package using your favorite package manager:

```bash
npm install @internationalized/date
```

It's highly recommended to familiarize yourself with the package's documentation before diving into the components. We'll cover the basics of how we use the package in Bits UI in the sections below, but their documentation provides much more detail on the various formats and how to work with them.

## DateValue

We use the `DateValue` objects provided by `@internationalized/date` to represent dates and times in a consistent way. These objects are immutable and provide information about the type of date they represent. The `DateValue` is a union of the following three types:

- `CalendarDate` \- Represents a date with no time component, such as `2024-07-10` - `CalendarDateTime` \- Represents a date and time, such as `2024-07-10T12:30:00` - `ZonedDateTime` \- Represents a date and time with a time zone, such as `2023-10-11T21:00:00:00-04:00[America/New_York]` The benefit of using these objects is that they allow you to be very specific about the type of date you want, and the component will adapt to that type. For example, if you pass a `CalendarDate` object to a `DateField` component, it will only display the date portion of the date, without the time. See the [Date Field](/docs/components/date-field) component for more information.

### CalendarDate

The `CalendarDate` object represents a date with no time component, such as `2024-07-10`.

You can use the `CalendarDate` constructor to create a new `CalendarDate` object:

```ts
import { CalendarDate } from "@internationalized/date";
const date = new CalendarDate(2024, 7, 10);
```

You can also use the `parseDate` function to parse an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string into a `CalendarDate` object:

```ts
import { parseDate } from "@internationalized/date";
const date = parseDate("2024-07-10");
```

If you want to create a `CalendarDate` with the current date, you can use the `today` function. This function requires a timezone identifier as an argument, which can be passed in as a string, or by using `getLocalTimeZone` which returns the user's current time zone:

```ts
import { today, getLocalTimeZone } from "@internationalized/date";
const losAngelesToday = today("America/Los_Angeles");
const localToday = today(getLocalTimeZone());
```

See the [CalendarDate API documentation](https://react-spectrum.adobe.com/internationalized/date/CalendarDate.html) for more information.

### CalendarDateTime

The `CalendarDateTime` object represents a date and time, such as `2024-07-10T12:30:00`.

You can use the `CalendarDateTime` constructor to create a new `CalendarDateTime` object:

```ts
import { CalendarDateTime } from "@internationalized/date";
const dateTime = new CalendarDateTime(2024, 7, 10, 12, 30, 0);
```

You can also use the `parseDateTime` function to parse an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string into a `CalendarDateTime` object:

```ts
import { parseDateTime } from "@internationalized/date";
const dateTime = parseDateTime("2024-07-10T12:30:00");
```

See the [CalendarDateTime API documentation](https://react-spectrum.adobe.com/internationalized/date/CalendarDateTime.html) for more information.

### ZonedDateTime

The `ZonedDateTime` object represents a date and time with a time zone, which represents an exact date and time in a specific time zone. `ZonedDateTimes` are often used for things such as in person events (concerts, conferences, etc.), where you want to represent a date and time in a *specific* time zone, rather than a specific date and time in the user's *local* time zone.

You can use the `ZonedDateTime` constructor to create a new `ZonedDateTime` object:

```ts
import { ZonedDateTime } from "@internationalized/date";
const date = new ZonedDateTime(
 // Date
 2022,
 2,
 3,
 // Time zone and UTC offset
 "America/Los_Angeles",
 -28800000,
 // Time
 9,
 15,
 0
);
```

You can also use one of the following parsing functions to parse an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string into a `ZonedDateTime` object:

```ts
import { parseZonedDateTime, parseAbsolute, parseAbsoluteToLocal } from "@internationalized/date";
const date = parseZonedDateTime("2024-07-12T00:45[America/New_York]");
// or
const date = parseAbsolute("2024-07-12T07:45:00Z", "America/New_York");
// or
const date = parseAbsoluteToLocal("2024-07-12T07:45:00Z");
```

See the [ZonedDateTime API documentation](https://react-spectrum.adobe.com/internationalized/date/ZonedDateTime.html) for more information.

## Date Ranges

Bits UI also provides a `DateRange` type with the following structure:

```ts
type DateRange = {
 start: DateValue;
 end: DateValue;
};
```

This type is used to represent the value of the various date range components in Bits UI, such as the [Date Range Field](/docs/components/date-range-field), [Date Range Picker](/docs/components/date-range-picker), and [Range Calendar](/docs/components/range-calendar).

## Placeholder

Each of the date/time components in Bits UI has a *bindable* `placeholder` prop, which acts as the starting point for the component when no value is present. The placeholder value is used to determine the type of date/time to display, and the component and its value will adapt to that type.

For example, if you pass a `CalendarDate` object to a `DateField` component, it will only display the date portion of the date, without the time. If you pass a `CalendarDateTime` object, it will display the date and time. If you pass a `ZonedDateTime` object, it will display the date and time with the time zone information.

In addition to setting the starting point and type of the date/time, the placeholder is also used to control the view of the calendar. For example, if you wanted to give the user the ability to select a specific month to jump to in the calendar, you could simply update the placeholder to a `DateValue` representing that month. Here's an example of how you might do that:

```svelte
<script lang="ts">
 import { Calendar } from "bits-ui";
 import { today, getLocalTimeZone, type DateValue } from "@internationalized/date";
 let placeholder: DateValue = $state(today(getLocalTimeZone()));
 let selectedMonth: number = $state(placeholder.month);
</script>
<select
 onchange={() => {
  placeholder = placeholder.set({ month: selectedMonth });
 }}
 bind:value={selectedMonth}
>
 <option value={1}>January</option>
 <option value={2}>February</option>
</select>
<Calendar.Root bind:placeholder>
</Calendar.Root>
```

In the example above, we're using the `placeholder` value to control the view of the calendar. The user can select a specific month to jump to in the calendar, and the placeholder will be updated to reflect the selected month. When the placeholder is updated, the calendar view will automatically update to reflect that new month.

As the user interacts with the calendar, the placeholder will be updated to reflect the currently focused date in the calendar. If a value is selected in the calendar, the placeholder will be updated to reflect that selected value.

### Updating the placeholder

It's important to note that `DateValue` objects are immutable, so you can't directly update the `placeholder` value. Instead, you'll need to reassign the value to the `placeholder` prop for the changes to reflect. `@internationalized/date` provides a number of methods for updating the `DateValue` objects, such as `set`, `add`, `subtract`, and `cycle`, each of which will return a new `DateValue` object with the updated value.

For example, if you wanted to update the placeholder to the next month, you could use the `add` method to add one month to the current month in the `placeholder` value:

```ts
let placeholder = new CalendarDate(2024, 07, 10);
console.log(placeholder.add({ months: 1 })); // 2024-08-10
console.log(placeholder); // 2024-07-10 (unchanged)
placeholder = placeholder.add({ months: 1 });
console.log(placeholder); // 2024-08-10 (updated)
```

## Formatting Dates `@internationalized/date` provides a [`DateFormatter`](https://react-spectrum.adobe.com/internationalized/date/DateFormatter.html) class that is a wrapper around the [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) API that fixes various browser bugs, and polyfills new features.

It's highly recommended to use this class to format dates and times in your application, as it will ensure that the formatting is accurate for all locales, time zones, and calendars.

## Parsing Dates

Often, you'll want to parse a string from a database or other source into a `DateValue` object for use with the date/time components in Bits UI. `@internationalized/date` provides various parsing functions that can be used to parse strings into each of the supported `DateValue` objects.

### parseDate

The `parseDate` function is used to parse a string into a `CalendarDate` object.

----------------------------------------------------

# Getting Started Documentation

Learn how to get started using Bits in your app.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

## Installation

Install bits using your favorite package manager.

```bash
npm install bits-ui
```

You can then import and start using them in your app.

```svelte
<script lang="ts">
 import { Accordion } from "bits-ui";
</script>
<Accordion.Root>
 <Accordion.Item>
  <Accordion.Header>
   <Accordion.Trigger>First</Accordion.Trigger>
  </Accordion.Header>
  <Accordion.Content>First accordion content</Accordion.Content>
 </Accordion.Item>
 <Accordion.Item>
  <Accordion.Header>
   <Accordion.Trigger>Second</Accordion.Trigger>
  </Accordion.Header>
  <Accordion.Content>Second accordion content</Accordion.Content>
 </Accordion.Item>
 <Accordion.Item>
  <Accordion.Header>
   <Accordion.Trigger>Third</Accordion.Trigger>
  </Accordion.Header>
  <Accordion.Content>Third accordion content</Accordion.Content>
 </Accordion.Item>
</Accordion.Root>
```

----------------------------------------------------

# LLMs Documentation

How to access LLM-friendly versions of Bits UI documentation.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

At the top of each documentation page, you'll find a convenient "Copy Markdown" button alongside a direct link to the LLM-friendly version of that page (e.g., `/llms.txt`). These tools make it easy to copy the content in Markdown format or access the machine-readable `llms.txt` file tailored for that specific page.

Bits UI documentation is designed to be accessible not only to humans but also to large language models (LLMs). We've adopted the [llms.txt](https://llmstxt.org/) proposal standard, which provides a structured, machine-readable format optimized for LLMs. This enables developers, researchers, and AI systems to efficiently parse and utilize our documentation.

## What is llms.txt?

The `llms.txt` standard is an emerging convention for presenting documentation in a simplified, text-based format that's easy for LLMs to process. By following this standard, Bits UI ensures compatibility with AI tools and workflows, allowing seamless integration into LLM-powered applications, research, or automation systems.

## Accessing LLM-friendly Documentation

To access the LLM-friendly version of any supported Bits UI documentation page, simply append `/llms.txt` to the end of the page's URL. This will return the content in a plain-text, LLM-optimized format.

### Example

- **Standard Page**: The Accordion component documentation is available at [bits-ui.com/docs/components/accordion](https://bits-ui.com/docs/components/accordion)
  .
- **LLM-friendly Version**: Append `/llms.txt` to access it at
  [bits-ui.com/docs/components/accordion/llms.txt](https://bits-ui.com/docs/components/accordion/llms.txt)
  .

### Root Index

To explore all supported pages in LLM-friendly format, visit the root index at [bits-ui.com/llms.txt](https://bits-ui.com/llms.txt). This page provides a comprehensive list of available documentation endpoints compatible with the `llms.txt` standard.

## Full LLM-friendly Documentation

For a complete, consolidated view of the Bits UI documentation in an LLM-friendly format, navigate to [bits-ui.com/docs/llms.txt](https://bits-ui.com/docs/llms.txt). This single endpoint aggregates all documentation content into a machine-readable structure, ideal for bulk processing or ingestion into AI systems.

## Notes

- Not all pages may support the `/llms.txt` suffix (those deemed irrelevant to LLMs, such as the Figma page). Check the root
  [bits-ui.com/llms.txt](https://bits-ui.com/llms.txt)
  page for an up-to-date list of compatible URLs.
- The "Copy Markdown" button at the top of each page provides the same content you'd find in the `/llms.txt` of that page.

By embracing the `llms.txt` standard, Bits UI empowers both human developers and AI systems to make the most of our documentation. Whether you're building with Bits UI or training an LLM, these tools are designed to enhance your experience.

----------------------------------------------------

# Ref Documentation

Learn about the $bindable ref prop.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

Bits UI components with underlying HTML elements provide a `ref` prop for direct element access.

For example, `Accordion.Trigger`'s `ref` gives access to its rendered `HTMLButtonElement`:

```svelte
<script lang="ts">
 import { Accordion } from "bits-ui";
 let triggerRef = $state<HTMLButtonElement | null>(null);
 function focusTrigger() {
  triggerRef?.focus();
 }
</script>
<button onclick={focusTrigger}>Focus trigger</button>
<Accordion.Trigger bind:ref={triggerRef}>
</Accordion.Trigger>
```

## With delegation

Bits UI tracks the reference to the underlying element using its `id` attribute. This means that even if you use a custom element/component with [delegation](/docs/child-snippet), the `ref` prop will still work.

```svelte
<script lang="ts">
 import CustomButton from "./CustomButton.svelte";
 import { Accordion } from "bits-ui";
 let triggerRef = $state<HTMLButtonElement | null>(null);
 function focusTrigger() {
  triggerRef?.focus();
 }
</script>
<Accordion.Trigger bind:ref={triggerRef}>
 {#snippet child({ props })}
  <CustomButton {...props} />
 {/snippet}
</Accordion.Trigger>
```

One caveat is that if you wish to use a custom `id` on the element, you must pass it to the component first, so it can be registered and associated with the `ref` prop. The `id` you pass will be passed down via the `props` snippet prop on the `child` snippet.

```svelte
<script lang="ts">
 import CustomButton from "./CustomButton.svelte";
 import { Accordion } from "bits-ui";
 let triggerRef = $state<HTMLButtonElement | null>(null);
 function focusTrigger() {
  triggerRef?.focus();
 }
 const myCustomId = "my-custom-id";
</script>
<Accordion.Trigger bind:ref={triggerRef} id={myCustomId}>
 {#snippet child({ props })}
  <CustomButton {...props} /> 
 {/snippet}
</Accordion.Trigger>
```

The following example would not work, as the `Accordion.Trigger` component has no idea what the `id` of the `CustomButton` is.

```svelte
<script lang="ts">
 import CustomButton from "./CustomButton.svelte";
 import { Accordion } from "bits-ui";
 let triggerRef = $state<HTMLButtonElement | null>(null);
 function focusTrigger() {
  triggerRef?.focus(); // will always be undefined
 }
</script>
<Accordion.Trigger bind:ref={triggerRef}>
 {#snippet child({ props })}
  <CustomButton {...props} id="my-custom-id" /> 
 {/snippet}
</Accordion.Trigger>
```

## Why Possibly `null`?

The `ref` prop may be `null` until the element has mounted, especially with the many components that use conditional rendering. This `HTMLElement | null` type mimics browser DOM methods like `getElementById`.

## WithElementRef

Bits UI exposes a [`WithElementRef`](/docs/type-helpers/with-element-ref) type which enables you to create your own components following the same `ref` prop pattern.

----------------------------------------------------

# State Management Documentation

How to manage the state of Bits UI components

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

State management is a critical aspect of modern UI development. Bits UI components support multiple approaches to manage component state, giving you flexibility based on your specific needs.

Each component's API reference will highlight what props are `bindable`. You can replace the `value` prop used in the examples on this page with any `bindable` prop.

## Two-Way Binding

The simplest approach is using Svelte's built-in two-way binding with `bind:`:

```svelte
<script lang="ts">
 import { ComponentName } from "bits-ui";
 let myValue = $state("default-value");
</script>
<button onclick={() => (myValue = "new-value")}> Update Value </button>
<ComponentName.Root bind:value={myValue}></ComponentName.Root>
```

### Why Use It?

- Zero-boilerplate state updates  
- External controls work automatically  
- Great for simple use cases ## Function Binding

For complete control, use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) that handles both getting and setting values:

```svelte
<script lang="ts">
 import { ComponentName } from "bits-ui";
 let myValue = $state("default-value");
 function getValue() {
  return myValue;
 }
 function setValue(newValue: string) {
  // Only update during business hours
  const now = new Date();
  const hour = now.getHours();
  if (hour >= 9 && hour <= 17) {
   myValue = newValue;
  }
 }
</script>
<ComponentName.Root bind:value={getValue, setValue}></ComponentName.Root>
```

When the component wants to set the value from an internal action, it will invoke the setter, where you can determine if the setter actually updates the state or not.

### When to Use

- Complex state transformation logic  
- Conditional updates  
- Debouncing or throttling state changes  
- Maintaining additional state alongside the primary value  
- Integrating with external state systems

----------------------------------------------------

# Styling Documentation

Learn how to style Bits UI components.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

We ship almost zero styles with Bits UI. This is intentional. We want to give you the most flexibility possible when it comes to styling your components.

For each component that renders an HTML element, we expose a `class` prop that you can use to apply styles to the component. This is the recommended and most straightforward way to style them.

## CSS frameworks

If you're using a CSS framework like TailwindCSS or UnoCSS, you can simply pass the classes you need to the component, and they will be applied to the underlying HTML element.

```svelte
<script lang="ts">
 import { Button } from "bits-ui";
</script>
<Button.Root class="h-12 w-full bg-blue-500 hover:bg-blue-600">Click me</Button.Root>
```

## Data attributes

A data attribute is applied to each element rendered by Bits UI, which you can use to target the component across your entire application. Check out the API reference of the component to determine what those data attributes are.

You can then use those data attributes like so:

#### Define global styles

src/app.pcss

```css
[data-button-root] {
 height: 3rem;
 width: 100%;
 background-color: #3182ce;
 color: #fff;
}
```

#### Import stylesheet

src/routes/+layout.svelte

```svelte
<script lang="ts">
 import "../app.pcss";
 let { children } = $props();
</script>
{@render children()}
```

Now every `<Button.Root />` component will have the styles applied to it.

## Global classes

If you prefer the class approach, you can simply apply your global classes to the component.

#### 1. Define global styles

src/app.pcss

```css
.button {
 height: 3rem;
 width: 100%;
 background-color: #3182ce;
 color: #fff;
}
```

#### 2. Apply global styles

src/routes/+layout.svelte

```svelte
<script lang="ts">
 import "../app.pcss";
 let { children } = $props();
</script>
{@render children()}
```

#### 3. Use with components

Button.svelte

```svelte
<script lang="ts">
 import { Button } from "bits-ui";
</script>
<Button.Root class="button">Click me</Button.Root>
```

## Scoped Styles

If you wish to use Svelte's scoped styles, you must use the `child` snippet for the various components that support it. This moves the underlying HTML element out of the Bits UI component scope and into the scope of your component.

See the [Child Snippet](/docs/child-snippet) documentation for more information.

## Style Prop

Bits UI components accept a `style` prop, which can either be a string or an object of CSS properties and values. These are gracefully merged with the component's internal styles to create a single style object using the [`mergeProps`](/docs/utilities/merge-props) function.

----------------------------------------------------

# Transitions Documentation

Learn how to use transitions with Bits UI components.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

Svelte Transitions are one of the awesome features of Svelte. Unfortunately, they don't play very nicely with components, due to the fact that they rely on various directives like `in:`, `out:`, and `transition:`, which aren't supported by components.

In previous version of Bits UI, we had a workaround for this by exposing a ton of `transition*` props on the components that we felt were most likely to be used with transitions. However, this was a bit of a hack and limited us to *only* Svelte Transitions, and users who wanted to use other libraries or just CSS were left out.

With Bits UI for Svelte 5, we've completely removed this workaround and instead exposed props and snippets that allow you to use any animation or transitions library you want.

## The Defaults

By default, Bits UI components handle the mounting and unmounting of specific components for you. They are wrapped in a component that ensures the component waits for transitions to finish before unmounting.

You can use any CSS transitions or animations you want with this approach, which is what we're doing in the various example components in this documentation, using [tailwindcss-animate](https://github.com/jamiebuilds/tailwindcss-animate).

## Force Mounting

On each component that we conditionally render, a `forceMount` prop is exposed. If set to `true`, the component will be forced to mount in the DOM and become visible to the user. You can use this prop in conjunction with the [delegated](/docs/child-snippet) `child` snippet to conditionally render the component and apply Svelte Transitions or another animation library.

The `child` snippet exposes a prop that you can use to conditionally render the element and apply your transitions.

```svelte
<script lang="ts">
 import { Dialog } from "bits-ui";
 import { fly } from "svelte/transition";
</script>
<Dialog.Root>
 <Dialog.Content forceMount>
  {#snippet child({ props, open })}
   {#if open}
    <div {...props} transition:fly>
    </div>
   {/if}
  {/snippet}
 </Dialog.Content>
</Dialog.Root>
```

In the example above, we're using the `forceMount` prop to tell the component to forcefully mount the `Dialog.Content` component. We're then using the `child` snippet to delegate the rendering of the `Dialog.Content` to a `div` element which we can apply our props and transitions to.

We understand this isn't the prettiest syntax, but it enables us to cover every use case. If you intend to use this approach across your application, it's recommended to create a reusable component that handles this logic, like so:

MyDialogContent.svelte

```svelte
<script lang="ts">
 import type { Snippet } from "svelte";
 import { fly } from "svelte/transition";
 import { Dialog, type WithoutChildrenOrChild } from "bits-ui";
 let {
  ref = $bindable(null),
  children,
  ...restProps
 }: WithoutChildrenOrChild<Dialog.ContentProps> & {
  children?: Snippet;
 } = $props();
</script>
<Dialog.Content bind:ref {...restProps} forceMount={true}>
 {#snippet child({ props, open })}
  {#if open}
   <div {...props} transition:fly>
    {@render children?.()}
   </div>
  {/if}
 {/snippet}
</Dialog.Content>
```

Which can then be used alongside the other `Dialog.*` components:

```svelte
<script lang="ts">
 import { Dialog } from "bits-ui";
 import MyDialogContent from "$lib/components/MyDialogContent.svelte";
</script>
<Dialog.Root>
 <Dialog.Trigger>Open Dialog</Dialog.Trigger>
 <Dialog.Portal>
  <Dialog.Overlay />
  <MyDialogContent>
   <Dialog.Title>Dialog Title</Dialog.Title>
   <Dialog.Description>Dialog Description</Dialog.Description>
   <Dialog.Close>Close</Dialog.Close>
   <div>Other dialog content</div>
  </MyDialogContent>
 </Dialog.Portal>
</Dialog.Root>
```

### Floating Content Components `Content` components that rely on Floating UI require a slight modification to how the `child` snippet is used.

For example, if we were to use the `Popover.Content` component, we need to add a wrapper element within the `child` snippet, and spread the `wrapperProps` snippet prop to it.

```svelte
<script lang="ts">
 import { Popover } from "bits-ui";
 import { fly } from "svelte/transition";
</script>
<Popover.Root>
 <Popover.Trigger>Open Popover</Popover.Trigger>
 <Popover.Portal>
  <Popover.Content forceMount>
   {#snippet child({ wrapperProps, props, open })}
    {#if open}
     <div {...wrapperProps}>
      <div {...props} transition:fly>
      </div>
     </div>
    {/if}
   {/snippet}
  </Popover.Content>
 </Popover.Portal>
</Popover.Root>
```

----------------------------------------------------

# Accordion Documentation

Organizes content into collapsible sections, allowing users to focus on one or more sections at a time.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { Accordion } from "bits-ui";
  import CaretDown from "phosphor-svelte/lib/CaretDown";
  const items = [
    {
      value: "1",
      title: "What is the meaning of life?",
      content:
        "To become a better person, to help others, and to leave the world a better place than you found it."
    },
    {
      value: "2",
      title: "How do I become a better person?",
      content:
        "Read books, listen to podcasts, and surround yourself with people who inspire you."
    },
    {
      value: "3",
      title: "What is the best way to help others?",
      content: "Give them your time, attention, and love."
    }
  ];
</script>
<Accordion.Root class="w-full sm:max-w-[70%]" type="multiple">
  {#each items as item (item.value)}
    <Accordion.Item
      value={item.value}
      class="border-dark-10 group border-b px-1.5"
    >
      <Accordion.Header>
        <Accordion.Trigger
          class="flex w-full flex-1 select-none items-center justify-between py-5 text-[15px] font-medium transition-all [&[data-state=open]>span>svg]:rotate-180"
        >
          <span class="w-full text-left">
            {item.title}
          </span>
          <span
            class="hover:bg-dark-10 inline-flex size-8 items-center justify-center rounded-[7px] bg-transparent"
          >
            <CaretDown class="size-[18px] transition-transform duration-200" />
          </span>
        </Accordion.Trigger>
      </Accordion.Header>
      <Accordion.Content
        class="data-[state=closed]:animate-accordion-up data-[state=open]:animate-accordion-down overflow-hidden text-sm tracking-[-0.01em]"
      >
        <div class="pb-[25px]">
          {item.content}
        </div>
      </Accordion.Content>
    </Accordion.Item>
  {/each}
</Accordion.Root>
```

## Overview

The Accordion component is a versatile UI element designed to manage large amounts of content by organizing it into collapsible sections. It's ideal for FAQs, settings panels, or any interface where users need to focus on specific information without being overwhelmed by visual clutter.

## Key Features

- **Single or Multiple Mode**: Toggle between allowing one open section or multiple sections at once.  
- **Accessible by Default**: Built-in ARIA attributes and keyboard navigation support.  
- **Smooth Transitions**: Leverage CSS variables or Svelte transitions for animated expansions.  
- **Flexible State**: Use uncontrolled defaults or take full control with bound values. ## Structure

The Accordion is a compound component made up of several sub-components:

- **`Root`**: Wraps all items and manages state.  
- **`Item`**: Represents a single collapsible section.  
- **`Header`**: Displays the title or label.  
- **`Trigger`**: The clickable element that toggles the content.  
- **`Content`**: The collapsible body of each item. Here's a basic example:

```svelte
<script lang="ts">
 import { Accordion } from "bits-ui";
</script>
<Accordion.Root>
 <Accordion.Item value="item-1">
  <Accordion.Header>
   <Accordion.Trigger>Section 1</Accordion.Trigger>
  </Accordion.Header>
  <Accordion.Content>Content for section 1 goes here.</Accordion.Content>
 </Accordion.Item>
</Accordion.Root>
```

## Reusable Components

To streamline usage in larger applications, create custom wrapper components for repeated patterns. Below is an example of a reusable `MyAccordionItem` and `MyAccordion`.

### Item Wrapper

Combines `Item`, `Header`, `Trigger`, and `Content` into a single component:

MyAccordionItem.svelte

```svelte
<script lang="ts">
 import { Accordion, type WithoutChildrenOrChild } from "bits-ui";
 type Props = WithoutChildrenOrChild<Accordion.ItemProps> & {
  title: string;
  content: string;
 };
 let { title, content, ...restProps }: Props = $props();
</script>
<Accordion.Item {...restProps}>
 <Accordion.Header>
  <Accordion.Trigger>{item.title}</Accordion.Trigger>
 </Accordion.Header>
 <Accordion.Content>
  {content}
 </Accordion.Content>
</Accordion.Item>
```

### Accordion Wrapper

Wraps `Root` and renders multiple `MyAccordionItem` components:

MyAccordion.svelte

```svelte
<script lang="ts">
 import { Accordion, type WithoutChildrenOrChild } from "bits-ui";
 import MyAccordionItem from "$lib/components/MyAccordionItem.svelte";
 type Item = {
  value?: string;
  title: string;
  content: string;
  disabled?: boolean;
 };
 let {
  value = $bindable(),
  ref = $bindable(null),
  ...restProps
 }: WithoutChildrenOrChild<Accordion.RootProps> & {
  items: Item[];
 } = $props();
</script>

<Accordion.Root bind:value bind:ref {...restProps as any}>
 {#each items as item, i (item.title + i)}
  <MyAccordionItem {...item} />
 {/each}
</Accordion.Root>
```

### Usage Example

+page.svelte

```svelte
<script lang="ts">
 import MyAccordion from "$lib/components/MyAccordion.svelte";
 const items = [
  { title: "Item 1", content: "Content 1" },
  { title: "Item 2", content: "Content 2" },
 ];
</script>
<MyAccordion type="single" {items} />
```

##### Tip

Use unique `value` props for each `Item` if you plan to control the state programatically.

## Managing Value State

This section covers how to manage the `value` state of the Accordion.

### Two-Way Binding

Use `bind:value` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { Accordion } from "bits-ui";
 let myValue = $state<string[]>([]);
 const numberOfItemsOpen = $derived(myValue.length);
</script>
<button
 onclick={() => {
  myValue = ["item-1", "item-2"];
 }}
>
 Open Items 1 and 2
</button>
<Accordion.Root type="multiple" bind:value={myValue}>
 <Accordion.Item value="item-1">
 </Accordion.Item>
 <Accordion.Item value="item-2">
 </Accordion.Item>
 <Accordion.Item value="item-3">
 </Accordion.Item>
</Accordion.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { Accordion } from "bits-ui";
 let myValue = $state("");
 function getValue() {
  return myValue;
 }
 function setValue(newValue: string) {
  myValue = newValue;
 }
</script>
<Accordion.Root type="single" bind:value={getValue, setValue}>
</Accordion.Root>
```

See the [State Management](/docs/state-management) documentation for more information.

## Customization

### Single vs. Multiple

Set the `type` prop to `"single"` to allow only one accordion item to be open at a time.

```svelte
<MyAccordion
 type="single"
 items={[
  { title: "Title A", content: "Content A" },
  { title: "Title B", content: "Content B" },
  { title: "Title C", content: "Content C" },
 ]}
/>
```

Set the `type` prop to `"multiple"` to allow multiple accordion items to be open at the same time.

```svelte
<MyAccordion
 type="multiple"
 items={[
  { title: "Title A", content: "Content A" },
  { title: "Title B", content: "Content B" },
  { title: "Title C", content: "Content C" },
 ]}
/>
```

### Default Open Items

Set the `value` prop to pre-open items:

```svelte
<MyAccordion value={["A", "C"]} type="multiple" />
```

### Disable Items

Disable specific items with the `disabled` prop:

```svelte
<Accordion.Root type="single">
 <Accordion.Item value="item-1" disabled>
 </Accordion.Item>
</Accordion.Root>
```

### Svelte Transitions

The Accordion component can be enhanced with Svelte's built-in transition effects or other animation libraries.

#### Using `forceMount` and `child` Snippets

To apply Svelte transitions to Accordion components, use the `forceMount` prop in combination with the `child` snippet. This approach gives you full control over the mounting behavior and animation of the `Accordion.Content`.

```svelte
<Accordion.Content forceMount={true}>
 {#snippet child({ props, open })}
  {#if open}
   <div {...props} transition:slide={{ duration: 1000 }}>
    This is the accordion content that will transition in and out.
   </div>
  {/if}
 {/snippet}
</Accordion.Content>
```

In this example:

- The `forceMount` prop ensures the components are always in the DOM.
- The `child` snippet provides access to the open state and component props.
- Svelte's `#if` block controls when the content is visible.
- Transition directives ( `transition:fade` and `transition:fly` ) apply the animations.

```svelte
<script lang="ts">
  import { Accordion } from "bits-ui";
  import CaretDown from "phosphor-svelte/lib/CaretDown";
  import { slide } from "svelte/transition";
  const items = [
    {
      title: "What is the meaning of life?",
      content:
        "To become a better person, to help others, and to leave the world a better place than you found it."
    },
    {
      title: "How do I become a better person?",
      content:
        "Read books, listen to podcasts, and surround yourself with people who inspire you."
    },
    {
      title: "What is the best way to help others?",
      content: "Give them your time, attention, and love."
    }
  ];
  let value = $state<string[]>([]);
</script>
<Accordion.Root class="w-full sm:max-w-[70%]" type="multiple" bind:value>
  {#each items as item, i}
    <Accordion.Item value={`${i}`} class="border-dark-10 group border-b px-1.5">
      <Accordion.Header>
        <Accordion.Trigger
          class="flex w-full flex-1 items-center justify-between py-5 text-[15px] font-medium transition-all [&[data-state=open]>span>svg]:rotate-180"
        >
          {item.title}
          <span
            class="hover:bg-dark-10 inline-flex size-8 items-center justify-center rounded-[7px] bg-transparent transition-all"
          >
            <CaretDown class="size-[18px] transition-all duration-200" />
          </span>
        </Accordion.Trigger>
      </Accordion.Header>
      <Accordion.Content
        forceMount={true}
        class="overflow-hidden text-sm tracking-[-0.01em]"
      >
        {#snippet child({ props, open })}
          {#if open}
            <div {...props} transition:slide={{ duration: 1000 }}>
              <div class="pb-[25px]">
                {item.content}
              </div>
            </div>
          {/if}
        {/snippet}
      </Accordion.Content>
    </Accordion.Item>
  {/each}
</Accordion.Root>
```

#### Best Practices

For cleaner code and better maintainability, consider creating custom reusable components that encapsulate this transition logic.

MyAccordionContent.svelte

```svelte
<script lang="ts">
 import { Accordion, type WithoutChildrenOrChild } from "bits-ui";
 import type { Snippet } from "svelte";
 import { fade } from "svelte/transition";
 let {
  ref = $bindable(null),
  duration = 200,
  children,
  ...restProps
 }: WithoutChildrenOrChild<Accordion.ContentProps> & {
  duration?: number;
  children: Snippet;
 } = $props();
</script>
<Accordion.Content forceMount bind:ref {...restProps}>
 {#snippet child({ props, open })}
  {#if open}
   <div {...props} transition:fade={{ duration }}>
    {@render children?.()}
   </div>
  {/if}
 {/snippet}
</Accordion.Content>
```

You can then use the `MyAccordionContent` component alongside the other `Accordion` primitives throughout your application:

```svelte
<Accordion.Root>
 <Accordion.Item value="A">
  <Accordion.Header>
   <Accordion.Trigger>A</Accordion.Trigger>
  </Accordion.Header>
  <MyAccordionContent duration={300}>
  </MyAccordionContent>
 </Accordion.Item>
</Accordion.Root>
```

## API Reference

### Accordion.Root

The root accordion component used to set and manage the state of the accordion.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` required | `enum`- 'single' \| 'multiple'                                       | The type of accordion. If set to `'multiple'`, the accordion will allow multiple items to be open at the same time. If set to `single`, the accordion will only allow a single item to be open.`Default:  undefined`           |
| `value` $bindable                            | `union`- string\[] \| string                                         | The value of the currently active accordion item. If `type` is `'single'`, this should be a string. If `type` is `'multiple'`, this should be an array of strings.`Default:  undefined`                                        |
| `onValueChange`                                           | `function`- string \| string\[]                                      | A callback function called when the active accordion item value changes. If the `type` is `'single'`, the argument will be a string. If `type` is `'multiple'`, the argument will be an array of strings.`Default:  undefined` |
| `disabled`                                                | `boolean`                                                                                                                                                                                            | Whether or not the accordion is disabled. When disabled, the accordion cannot be interacted with.`Default: false`                                                                                                                 |
| `loop`                                                    | `boolean`                                                                                                                                                                                            | Whether or not the accordion should loop through items when reaching the end.`Default: false`                                                                                                                                     |
| `orientation`                                             | `enum`- 'vertical' \| 'horizontal'                                   | The orientation of the accordion.`Default: vertical`                                                                                                                                                                              |
| `ref` $bindable                              | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                 | | Data Attribute                                   | Value                                                                                                                                                                                                 | Description                                                                                     |
| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-orientation` | `enum`- 'vertical' \| 'horizontal' | The orientation of the component.                                        |
| `data-disabled`                                         | `''`                                                                                                                                                                                         | Present when the component is disabled.                                  |
| `data-accordion-root`                                   | `''`                                                                                                                                                                                         | Present on the root element. |

### Accordion.Item

An accordion item.

| Property                                                                  | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                          |
| ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `disabled` | `boolean`                                                                                                                                                                                            | Whether or not the accordion item is disabled.`Default: false`                                                                                                                         |
| `value`                                 | `string`                                                                                                                                                                                             | The value of the accordion item. This is used to identify when the item is open or closed. If not provided, a unique ID will be generated for this value.`Default: A random unique ID` |
| `ref` $bindable            | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                             |
| `children`                              | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                                |
| `child`                                 | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`      | | Data Attribute                             | Value                                                                                                                                                                                                 | Description                                                                                     |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed'         | Whether the accordion item is open or closed.                            |
| `data-disabled`                                   | `''`                                                                                                                                                                                         | Present when the component is disabled.                                  |
| `data-orientation`                                | `enum`- 'vertical' \| 'horizontal' | The orientation of the component.                                        |
| `data-accordion-item`                             | `''`                                                                                                                                                                                         | Present on the item element. |

### Accordion.Header

The header of the accordion item.

| Property                                                               | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `level` | `union`- 1 \| 2 \| 3 \| 4 \| 5 \| 6                                  | The heading level of the header. This will be set as the `aria-level` attribute.`Default: 3`                                                                                      |
| `ref` $bindable         | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                           | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                              | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                   | Value                                                                                                                                                                                                             | Description                                                                                       |
| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-orientation` | `enum`- 'vertical' \| 'horizontal'             | The orientation of the component.                                          |
| `data-disabled`                                         | `''`                                                                                                                                                                                                     | Present when the component is disabled.                                    |
| `data-heading-level`                                    | `enum`- '1' \| '2' \| '3' \| '4' \| '5' \| '6' | The heading level of the element.                                          |
| `data-accordion-header`                                 | `''`                                                                                                                                                                                                     | Present on the header element. |

### Accordion.Trigger

The button responsible for toggling the accordion item.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                   | Value                                                                                                                                                                                                 | Description                                                                                        |
| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-orientation` | `enum`- 'vertical' \| 'horizontal' | The orientation of the component.                                           |
| `data-disabled`                                         | `''`                                                                                                                                                                                         | Present when the component is disabled.                                     |
| `data-accordion-trigger`                                | `''`                                                                                                                                                                                         | Present on the trigger element. |

### Accordion.Content

The accordion item content, which is displayed when the item is open.

| Property                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `forceMount` | `boolean`                                                                                                                                                                                            | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                |
| `ref` $bindable              | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                | `Snippet`- Snippet                                                   | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                   | Value                                                                                                                                                                                                 | Description                                                                                        |
| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-orientation` | `enum`- 'vertical' \| 'horizontal' | The orientation of the component.                                           |
| `data-disabled`                                         | `''`                                                                                                                                                                                         | Present when the component is disabled.                                     |
| `data-accordion-content`                                | `''`                                                                                                                                                                                         | Present on the content element. |

| CSS Variable                                                    | Description                                                                                                    |
| -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--bits-accordion-content-height` | The height of the accordion content element.                                            |
| `--bits-accordion-content-width`                                       | The width of the accordion content element. |

----------------------------------------------------

# Alert Dialog Documentation

A modal window that alerts users with important information and awaits their acknowledgment or action.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { AlertDialog } from "bits-ui";
</script>
<AlertDialog.Root>
  <AlertDialog.Trigger
    class="rounded-input bg-dark text-background
 shadow-mini hover:bg-dark/95 inline-flex h-12 select-none
 items-center justify-center whitespace-nowrap px-[21px] text-[15px] font-semibold transition-all active:scale-[0.98]"
  >
    Subscribe
  </AlertDialog.Trigger>
  <AlertDialog.Portal>
    <AlertDialog.Overlay
      class="data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 fixed inset-0 z-50 bg-black/80"
    />
    <AlertDialog.Content
      class="rounded-card-lg bg-background shadow-popover data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 outline-hidden fixed left-[50%] top-[50%] z-50 grid w-full max-w-[calc(100%-2rem)] translate-x-[-50%] translate-y-[-50%] gap-4 border p-7 sm:max-w-lg md:w-full "
    >
      <div class="flex flex-col gap-4 pb-6">
        <AlertDialog.Title class="text-lg font-semibold tracking-tight">
          Confirm your transaction
        </AlertDialog.Title>
        <AlertDialog.Description class="text-foreground-alt text-sm">
          This action cannot be undone. This will initiate a monthly wire in the
          amount of $10,000 to Huntabyte. Do you wish to continue?
        </AlertDialog.Description>
      </div>
      <div class="flex w-full items-center justify-center gap-2">
        <AlertDialog.Cancel
          class="h-input rounded-input bg-muted shadow-mini hover:bg-dark-10 focus-visible:ring-foreground focus-visible:ring-offset-background focus-visible:outline-hidden inline-flex w-full items-center justify-center text-[15px] font-medium transition-all focus-visible:ring-2 focus-visible:ring-offset-2 active:scale-[0.98]"
        >
          Cancel
        </AlertDialog.Cancel>
        <AlertDialog.Action
          class="h-input rounded-input bg-dark text-background shadow-mini hover:bg-dark/95 focus-visible:ring-dark focus-visible:ring-offset-background focus-visible:outline-hidden inline-flex w-full items-center justify-center text-[15px] font-semibold transition-all focus-visible:ring-2 focus-visible:ring-offset-2 active:scale-[0.98]"
        >
          Continue
        </AlertDialog.Action>
      </div>
    </AlertDialog.Content>
  </AlertDialog.Portal>
</AlertDialog.Root>
```

## Key Features

- **Compound Component Structure**: Build flexible, customizable alert dialogs using sub-components.  
- **Accessibility**: ARIA-compliant with full keyboard navigation support.  
- **Portal Support**: Render content outside the normal DOM hierarchy for proper stacking.  
- **Managed Focus**: Automatically traps focus with customization options.  
- **Flexible State**: Supports both controlled and uncontrolled open states. ## Structure

The Alert Dialog is built from sub-components, each with a specific purpose:

- **Root**: Manages state and provides context to child components.  
- **Trigger**: Toggles the dialog's open/closed state.  
- **Portal**: Renders its children in a portal, outside the normal DOM hierarchy.  
- **Overlay**: Displays a backdrop behind the dialog.  
- **Content**: Holds the dialog's main content.  
- **Title**: Displays the dialog's title.  
- **Description**: Displays a description or additional context for the dialog.  
- **Cancel**: Closes the dialog without action.  
- **Action**: Confirms the dialog's action. Here's a simple example of an Alert Dialog:

```svelte
<script lang="ts">
 import { AlertDialog } from "bits-ui";
</script>
<AlertDialog.Root>
 <AlertDialog.Trigger>Open Dialog</AlertDialog.Trigger>
 <AlertDialog.Portal>
  <AlertDialog.Overlay />
  <AlertDialog.Content>
   <AlertDialog.Title>Confirm Action</AlertDialog.Title>
   <AlertDialog.Description>Are you sure?</AlertDialog.Description>
   <AlertDialog.Cancel>Cancel</AlertDialog.Cancel>
   <AlertDialog.Action>Confirm</AlertDialog.Action>
  </AlertDialog.Content>
 </AlertDialog.Portal>
</AlertDialog.Root>
```

## Reusable Components

For consistency across your app, create a reusable Alert Dialog component. Here's an example:

MyAlertDialog.svelte

```svelte
<script lang="ts">
 import type { Snippet } from "svelte";
 import { AlertDialog, type WithoutChild } from "bits-ui";
 type Props = AlertDialog.RootProps & {
  buttonText: string;
  title: Snippet;
  description: Snippet;
  contentProps?: WithoutChild<AlertDialog.ContentProps>;
  // ...other component props if you wish to pass them
 };
 let {
  open = $bindable(false),
  children,
  buttonText,
  contentProps,
  title,
  description,
  ...restProps
 }: Props = $props();
</script>
<AlertDialog.Root bind:open {...restProps}>
 <AlertDialog.Trigger>
  {buttonText}
 </AlertDialog.Trigger>
 <AlertDialog.Portal>
  <AlertDialog.Overlay />
  <AlertDialog.Content {...contentProps}>
   <AlertDialog.Title>
    {@render title()}
   </AlertDialog.Title>
   <AlertDialog.Description>
    {@render description()}
   </AlertDialog.Description>
   {@render children?.()}
   <AlertDialog.Cancel>Cancel</AlertDialog.Cancel>
   <AlertDialog.Action>Confirm</AlertDialog.Action>
  </AlertDialog.Content>
 </AlertDialog.Portal>
</AlertDialog.Root>
```

You can then use the `MyAlertDialog` component in your application like so:

+page.svelte

```svelte
<script lang="ts">
 import MyAlertDialog from "$lib/components/MyAlertDialog.svelte";
</script>
<MyAlertDialog buttonText="Open Dialog">
 {#snippet title()}
  Delete your account
 {/snippet}
 {#snippet description()}
  This action cannot be undone.
 {/snippet}
</MyAlertDialog>
```

Alternatively, you can define the snippets separately and pass them as props to the component:

+page.svelte

```svelte
<script lang="ts">
 import MyAlertDialog from "$lib/components/MyAlertDialog.svelte";
</script>
{#snippet title()}
 Delete your account
{/snippet}
{#snippet description()}
 This action cannot be undone.
{/snippet}
<MyAlertDialog buttonText="Open Dialog" {title} {description}>
</MyAlertDialog>
```

##### Tip

Use string props for simplicity or snippets for dynamic content.

## Managing Open State

This section covers how to manage the `open` state of the Alert Dialog.

### Two-Way Binding

Use `bind:open` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { AlertDialog } from "bits-ui";
 let isOpen = $state(false);
</script>
<button onclick={() => (isOpen = true)}>Open Dialog</button>
<AlertDialog.Root bind:open={isOpen}>
</AlertDialog.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for total control:

```svelte
<script lang="ts">
 import { AlertDialog } from "bits-ui";
 let myOpen = $state(false);
 function getOpen() {
  return myOpen;
 }
 function setOpen(newOpen: boolean) {
  myOpen = newOpen;
 }
</script>
<AlertDialog.Root bind:open={getOpen, setOpen}>
</AlertDialog.Root>
```

See the [State Management](/docs/state-management) documentation for more information.

## Focus Management

### Focus Trap

Focus is trapped within the dialog by default. To disable:

```svelte
<AlertDialog.Content trapFocus={false}>
</AlertDialog.Content>
```

##### Warning

Disabling focus trap may reduce accessibility. Use with caution.

### Open Focus

By default, when a dialog is opened, focus will be set to the `AlertDialog.Cancel` button if it exists, or the first focusable element within the `AlertDialog.Content`. This ensures that users navigating my keyboard end up somewhere within the Dialog that they can interact with.

You can override this behavior using the `onOpenAutoFocus` prop on the `AlertDialog.Content` component. It's *highly* recommended that you use this prop to focus *something* within the Dialog.

You'll first need to cancel the default behavior of focusing the first focusable element by cancelling the event passed to the `onOpenAutoFocus` callback. You can then focus whatever you wish.

```svelte
<script lang="ts">
 import { AlertDialog } from "bits-ui";
 let nameInput = $state<HTMLInputElement>();
</script>
<AlertDialog.Root>
 <AlertDialog.Trigger>Open AlertDialog</AlertDialog.Trigger>
 <AlertDialog.Content
  onOpenAutoFocus={(e) => {
   e.preventDefault();
   nameInput?.focus();
  }}
 >
  <input type="text" bind:this={nameInput} />
 </AlertDialog.Content>
</AlertDialog.Root>
```

### Close Focus

By default, when a dialog is closed, focus will be set to the trigger element of the dialog. You can override this behavior using the `onCloseAutoFocus` prop on the `AlertDialog.Content` component.

You'll need to cancel the default behavior of focusing the trigger element by cancelling the event passed to the `onCloseAutoFocus` callback, and then focus whatever you wish.

```svelte
<script lang="ts">
 import { AlertDialog } from "bits-ui";
 let nameInput = $state<HTMLInputElement>();
</script>
<input type="text" bind:this={nameInput} />
<AlertDialog.Root>
 <AlertDialog.Trigger>Open AlertDialog</AlertDialog.Trigger>
 <AlertDialog.Content
  onCloseAutoFocus={(e) => {
   e.preventDefault();
   nameInput?.focus();
  }}
 >
 </AlertDialog.Content>
</AlertDialog.Root>
```

## Advanced Behaviors

The Alert Dialog component offers several advanced features to customize its behavior and enhance user experience. This section covers scroll locking, escape key handling, and interaction outside the dialog.

### Scroll Lock

By default, when an Alert Dialog opens, scrolling the body is disabled. This provides a more native-like experience, focusing user attention on the dialog content.

#### Customizing Scroll Behavior

To allow body scrolling while the dialog is open, use the `preventScroll` prop on `AlertDialog.Content`:

```svelte
<AlertDialog.Content preventScroll={false}>
</AlertDialog.Content>
```

##### Note

Enabling body scroll may affect user focus and accessibility. Use this option judiciously.

### Escape Key Handling

By default, pressing the `Escape` key closes an open Alert Dialog. Bits UI provides two methods to customize this behavior.

#### Method 1: `escapeKeydownBehavior` The `escapeKeydownBehavior` prop allows you to customize the behavior taken by the component when the `Escape` key is pressed. It accepts one of the following values:

- `'close'` (default): Closes the Alert Dialog immediately.
- `'ignore'` : Prevents the Alert Dialog from closing.
- `'defer-otherwise-close'` : If an ancestor Bits UI component also implements this prop, it will defer the closing decision to that component. Otherwise, the Alert Dialog will close immediately.
- `'defer-otherwise-ignore'` : If an ancestor Bits UI component also implements this prop, it will defer the closing decision to that component. Otherwise, the Alert Dialog will ignore the key press and not close.

To always prevent the Alert Dialog from closing on Escape key press, set the `escapeKeydownBehavior` prop to `'ignore'` on `Dialog.Content`:

```svelte
<AlertDialog.Content escapeKeydownBehavior="ignore">
</AlertDialog.Content>
```

#### Method 2: `onEscapeKeydown` For more granular control, override the default behavior using the `onEscapeKeydown` prop:

```svelte
<AlertDialog.Content
 onEscapeKeydown={(e) => {
  e.preventDefault();
  // do something else instead
 }}
>
</AlertDialog.Content>
```

This method allows you to implement custom logic when the `Escape` key is pressed.

### Interaction Outside

By default, interacting outside the Alert Dialog content area does not close the dialog. Bits UI offers two ways to modify this behavior.

#### Method 1: `interactOutsideBehavior` The `interactOutsideBehavior` prop allows you to customize the behavior taken by the component when an interaction (touch, mouse, or pointer event) occurs outside the content. It accepts one of the following values:

- `'ignore'` (default): Prevents the Alert Dialog from closing.
- `'close'` : Closes the Alert Dialog immediately.
- `'defer-otherwise-close'` : If an ancestor Bits UI component also implements this prop, it will defer the closing decision to that component. Otherwise, the Alert Dialog will close immediately.
- `'defer-otherwise-ignore'` : If an ancestor Bits UI component also implements this prop, it will defer the closing decision to that component. Otherwise, the Alert Dialog will ignore the event and not close.

To make the Alert Dialog close when an interaction occurs outside the content, set the `interactOutsideBehavior` prop to `'close'` on `AlertDialog.Content`:

```svelte
<AlertDialog.Content interactOutsideBehavior="ignore">
</AlertDialog.Content>
```

#### Method 2: `onInteractOutside` For custom handling of outside interactions, you can override the default behavior using the `onInteractOutside` prop:

```svelte
<AlertDialog.Content
 onInteractOutside={(e) => {
  e.preventDefault();
  // do something else instead
 }}
>
</AlertDialog.Content>
```

This approach allows you to implement specific behaviors when users interact outside the Alert Dialog content.

### Best Practices

- **Scroll Lock**: Consider your use case carefully before disabling scroll lock. It may be necessary for dialogs with scrollable content or for specific UX requirements.  
- **Escape Keydown**: Overriding the default escape key behavior should be done thoughtfully. Users often expect the escape key to close modals.  
- **Outside Interactions**: Ignoring outside interactions can be useful for important dialogs or multi-step processes, but be cautious not to trap users unintentionally.  
- **Accessibility**: Always ensure that any customizations maintain or enhance the dialog's accessibility.  
- **User Expectations**: Try to balance custom behaviors with common UX patterns to avoid confusing users. By leveraging these advanced features, you can create highly customized dialog experiences while maintaining usability and accessibility standards.

## Nested Dialogs

Dialogs can be nested within each other to create more complex layouts. See the [Dialog](/docs/components/dialog) component for more information on nested dialogs.

## Svelte Transitions

See the [Dialog](/docs/components/dialog) component for more information on Svelte Transitions with dialog components.

## Working with Forms

### Form Submission

When using the `AlertDialog` component, often you'll want to submit a form or perform an asynchronous action when the user clicks the `Action` button.

This can be done by waiting for the asynchronous action to complete, then programmatically closing the dialog.

```svelte
<script lang="ts">
 import { AlertDialog } from "bits-ui";
 function wait(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
 }
 let open = $state(false);
</script>
<AlertDialog.Root bind:open>
 <AlertDialog.Portal>
  <AlertDialog.Overlay />
  <AlertDialog.Content>
   <AlertDialog.Title>Confirm your action</AlertDialog.Title>
   <AlertDialog.Description>Are you sure you want to do this?</AlertDialog.Description>
   <form
    method="POST"
    action="?/someAction"
    onsubmit={() => {
     wait(1000).then(() => (open = false));
    }}
   >
    <AlertDialog.Cancel type="button">No, cancel (close dialog)</AlertDialog.Cancel>
    <AlertDialog.Action type="submit">Yes (submit form)</AlertDialog.Action>
   </form>
  </AlertDialog.Content>
 </AlertDialog.Portal>
</AlertDialog.Root>
```

### Inside a Form

If you're using an `AlertDialog` *within* a form, you'll need to ensure that the `Portal` is disabled or not included in the `AlertDialog` structure. This is because the `Portal` will render the dialog content *outside* of the form, which will prevent the form from being submitted correctly.

## API Reference

### AlertDialog.Root

The root component used to set and manage the state of the alert dialog.

| Property                                                                                     | Type                                                                                                                                                                                                           | Description                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `open` $bindable | `boolean`                                                                                                                                                           | Whether or not the alert dialog is open.`Default: false`                                    |
| `onOpenChange`                                             | `function`- (open: boolean) => void | A callback function called when the open state changes.`Default:  undefined`             |
| `children`                                                 | `Snippet`                                                                                                                                                           | The children content to render.`Default:  undefined` |

### AlertDialog.Trigger

The element which opens the alert dialog on press.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value                                                                                                                                                                         | Description                                                                                        |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- '' | The state of the alert dialog.                                              |
| `data-alert-dialog-trigger`                       | `''`                                                                                                                                                                 | Present on the trigger element. |

### AlertDialog.Content

The content displayed within the alert dialog modal.

| Property                                                                           | Type                                                                                                                                                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onInteractOutside` | `function`- (event: PointerEvent) => void                                          | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default:  undefined`                                                                                                                                                                                                        |
| `onFocusOutside`                                 | `function`- (event: FocusEvent) => void                                            | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default:  undefined`                                                                                                                                                                                                                                                  |
| `interactOutsideBehavior`                        | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close`  |
| `onEscapeKeydown`                                | `function`- (event: KeyboardEvent) => void                                         | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default:  undefined`                                                                                                                                                                                                                    |
| `escapeKeydownBehavior`                          | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` |
| `onOpenAutoFocus`                                | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is opened. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `onCloseAutoFocus`                               | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is closed. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `trapFocus`                                      | `boolean`                                                                                                                                                                                                          | Whether or not to trap the focus within the content when open.`Default: true`                                                                                                                                                                                                                                                                                                                                                      |
| `forceMount`                                     | `boolean`                                                                                                                                                                                                          | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                                                                                                                                                                                                                                                                 |
| `preventOverflowTextSelection`                   | `boolean`                                                                                                                                                                                                          | When `true`, prevents the text selection from overflowing the bounds of the element.`Default: true`                                                                                                                                                                                                                                                                                                                                |
| `preventScroll`                                  | `boolean`                                                                                                                                                                                                          | When `true`, prevents the body from scrolling when the content is open. This is useful when you want to use the content as a modal.`Default: true`                                                                                                                                                                                                                                                                                 |
| `restoreScrollDelay`                             | `number`                                                                                                                                                                                                           | The delay in milliseconds before the scrollbar is restored after closing the dialog. This is only applicable when using the `child` snippet for custom transitions and `preventScroll` and `forceMount` are `true`. You should set this to a value greater than the transition duration to prevent content from shifting during the transition.`Default: null`                                                                     |
| `ref` $bindable                     | `HTMLDivElement`                                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                                                                                                                                                                         |
| `children`                                       | `Snippet`                                                                                                                                                                                                          | The children content to render.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                                                            |
| `child`                                          | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };               | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                                                                                                                                                                  | | Data Attribute                             | Value                                                                                                                                                                         | Description                                                                                        |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- '' | The state of the alert dialog.                                              |
| `data-alert-dialog-content`                       | `''`                                                                                                                                                                 | Present on the content element. |

### AlertDialog.Overlay

An overlay which covers the body when the alert dialog is open.

| Property                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `forceMount` | `boolean`                                                                                                                                                                                            | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                |
| `ref` $bindable              | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value                                                                                                                                                                         | Description                                                                                        |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- '' | The state of the alert dialog.                                              |
| `data-alert-dialog-overlay`                       | `''`                                                                                                                                                                 | Present on the overlay element. |

### AlertDialog.Portal

A portal which renders the alert dialog into the body when it is open.

| Property                                                            | Type                                                                                                                                                                                                                           | Description                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `to` | `union`- string \| HTMLElement \| null \| undefined | Where to render the content when it is open. Defaults to the body. Can be disabled by passing `null``Default: body`              |
| `disabled`                        | `boolean`                                                                                                                                                                           | Whether the portal is disabled or not. When disabled, the content will be rendered in its original DOM location.`Default: false` |
| `children`                        | `Snippet`                                                                                                                                                                           | The children content to render.`Default:  undefined`                                      |

### AlertDialog.Action

The button responsible for taking an action within the alert dialog. This button does not close the dialog out of the box. See the [Form Submission](#form-submission) documentation for more information.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                           | Value         | Description                                                                                       |
| ------------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-alert-dialog-action` | `''` | Present on the action element. |

### AlertDialog.Cancel

A button used to close the alert dialog without taking an action.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                           | Value         | Description                                                                                       |
| ------------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-alert-dialog-cancel` | `''` | Present on the cancel element. |

### AlertDialog.Title

An accessible title for the alert dialog.

| Property                                                               | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `level` | `union`- 1 \| 2 \| 3 \| 4 \| 5 \| 6                                  | The heading level of the title. This will be set as the `aria-level` attribute.`Default: 3`                                                                                       |
| `ref` $bindable         | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                           | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                              | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                          | Value         | Description                                                                                      |
| ------------------------------------------------------------------------------------------ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-alert-dialog-title` | `''` | Present on the title element. |

### AlertDialog.Description

An accessible description for the alert dialog.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                                | Value         | Description                                                                                            |
| ------------------------------------------------------------------------------------------------ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-alert-dialog-description` | `''` | Present on the description element. |

----------------------------------------------------

# Aspect Ratio Documentation

Displays content while maintaining a specified aspect ratio, ensuring consistent visual proportions.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { AspectRatio } from "bits-ui";
</script>
<AspectRatio.Root
  ratio={14 / 9}
  class="rounded-15px scale-[0.8] bg-transparent"
>
  <img
    src="/abstract.png"
    alt="an abstract painting"
    class="h-full w-full rounded-[15px] object-cover"
  />
</AspectRatio.Root>
```

## Architecture

- **Root**: The root component which contains the aspect ratio logic ## Structure

Here's an overview of how the Aspect Ratio component is structured in code:

```svelte
<script lang="ts">
 import { AspectRatio } from "bits-ui";
</script>
<AspectRatio.Root />
```

## Reusable Component

If you plan on using a lot of `AspectRatio` components throughout your application, you can create a reusable component that combines the `AspectRatio.Root` and whatever other elements you'd like to render within it. In the following example, we're creating a reusable `MyAspectRatio` component that takes in a `src` prop and renders an `img` element with the `src` prop.

MyAspectRatio.svelte

```svelte
<script lang="ts">
 import { AspectRatio, type WithoutChildrenOrChild } from "bits-ui";
 let {
  src,
  alt,
  ref = $bindable(null),
  imageRef = $bindable(null),
  ...restProps
 }: WithoutChildrenOrChild<AspectRatio.RootProps> & {
  src: string;
  alt: string;
  imageRef?: HTMLImageElement | null;
 } = $props();
</script>
<AspectRatio.Root {...restProps} bind:ref>
 <img {src} {alt} bind:this={imageRef} />
</AspectRatio.Root>
```

You can then use the `MyAspectRatio` component in your application like so:

+page.svelte

```svelte
<script lang="ts">
 import MyAspectRatio from "$lib/components/MyAspectRatio.svelte";
</script>
<MyAspectRatio src="https://example.com/image.jpg" alt="an abstract painting" ratio={4 / 3} />
```

## Custom Ratio

Use the `ratio` prop to set a custom aspect ratio for the image.

```svelte
<AspectRatio.Root ratio={16 / 9}>
</AspectRatio.Root>
```

## API Reference

### AspectRatio.Root

The aspect ratio component.

| Property                                                               | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ratio` | `number`                                                                                                                                                                                             | The desired aspect ratio.`Default: 1`                                                                                                                                             |
| `ref` $bindable         | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                           | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                              | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                         | Value         | Description                                                                                     |
| ----------------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-aspect-ratio-root` | `''` | Present on the root element. |

----------------------------------------------------

# Avatar Documentation

Represents a user or entity with a recognizable image or placeholder in UI elements.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { Avatar } from "bits-ui";
  let loadingStatus = $state<Avatar.RootProps["loadingStatus"]>("loading");
</script>
<Avatar.Root
  bind:loadingStatus
  class="h-12 w-12 rounded-full border {loadingStatus === 'loaded'
    ? 'border-foreground'
    : 'border-transparent'} bg-muted text-muted-foreground text-[17px] font-medium uppercase"
>
  <div
    class="flex h-full w-full items-center justify-center overflow-hidden rounded-full border-2 border-transparent"
  >
    <Avatar.Image src="/avatar-1.png" alt="@huntabyte" />
    <Avatar.Fallback class="border-muted border">HB</Avatar.Fallback>
  </div>
</Avatar.Root>
```

## Overview

The Avatar component is designed to represent a user or entity within your application's user interface. It provides a flexible and accessible way to display profile pictures or placeholder images.

## Key Features

- **Compound Component Structure**: Offers a set of sub-components that work together to create a fully-featured avatar.  
- **Fallback Mechanism**: Provides a fallback when the primary image is unavailable or loading.  
- **Customizable**: Each sub-component can be styled and configured independently to match your design system. ## Architecture

The Avatar component is composed of several sub-components, each with a specific role:

- **Root**: The main container component that manages the state of the avatar.  
- **Image**: The primary image element that displays the user's profile picture or a representative image.  
- **Fallback**: The fallback element that displays alternative content when the primary image is unavailable or loading. ## Structure

Here's an overview of how the Avatar component is structured in code:

```svelte
<script lang="ts">
 import { Avatar } from "bits-ui";
</script>
<Avatar.Root>
 <Avatar.Image />
 <Avatar.Fallback />
</Avatar.Root>
```

## Reusable Components

You can create your own reusable components that combine the `Avatar` primitives and simplify the usage throughout your application. In the following example, we're creating a reusable `MyAvatar` component that takes in a `src` and `fallback` prop and renders an `Avatar.Root` component with an `Avatar.Image` and `Avatar.Fallback` component.

MyAvatar.svelte

```svelte
<script lang="ts">
 import { Avatar, type WithoutChildrenOrChild } from "bits-ui";
 let {
  src,
  alt,
  fallback,
  ref = $bindable(null),
  imageRef = $bindable(null),
  fallbackRef = $bindable(null),
  ...restProps
 }: WithoutChildrenOrChild<Avatar.RootProps> & {
  src: string;
  alt: string;
  fallback: string;
  imageRef?: HTMLImageElement | null;
  fallbackRef?: HTMLElement | null;
 } = $props();
</script>
<Avatar.Root {...restProps} bind:ref>
 <Avatar.Image {src} {alt} bind:ref={imageRef} />
 <Avatar.Fallback bind:ref={fallbackRef}>
  {fallback}
 </Avatar.Fallback>
</Avatar.Root>
```

You could then use the `MyAvatar` component in your application like so:

+page.svelte

```svelte
<script lang="ts">
 import MyAvatar from "$lib/components/MyAvatar.svelte";
</script>
<MyAvatar src="https://github.com/huntabyte.png" alt="huntabyte" fallback="HJ" />
```

## API Reference

### Avatar.Root

The root component used to set and manage the state of the avatar.

| Property                                                                                              | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                                         |
| ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `loadingStatus` $bindable | `enum`- 'loading' \| 'loaded' \| 'error'                             | The loading status of the avatars source image. You can bind a variable to track the status outside of the component and use it to show a loading indicator or error message.`Default:  undefined` |
| `onLoadingStatusChange`                                             | `function`- (status: LoadingStatus) => void                          | A callback function called when the loading status of the image changes.`Default:  undefined`                                                                                                      |
| `delayMs`                                                           | `number`                                                                                                                                                                                             | How long to wait before showing the image after it has loaded. This can be useful to prevent a harsh flickering effect when the image loads quickly.`Default: 0`                                      |
| `ref` $bindable                                        | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                            |
| `children`                                                          | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                                               |
| `child`                                                             | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                     | | Data Attribute                              | Value                                                                                                                                                                                                       | Description                                                                                     |
| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-status` | `enum`- 'loading' \| 'loaded' \| 'error' | The loading status of the image.                                         |
| `data-avatar-root`                                 | `''`                                                                                                                                                                                               | Present on the root element. |

### Avatar.Image

The avatar image displayed once it has loaded.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLImageElement`                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                              | Value                                                                                                                                                                                                       | Description                                                                                     |
| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-status` | `enum`- 'loading' \| 'loaded' \| 'error' | The loading status of the image.                                         |
| `data-avatar-image`                                | `''`                                                                                                                                                                                               | Present on the root element. |

### Avatar.Fallback

The fallback displayed while the avatar image is loading or if it fails to load

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLSpanElement`                                                                                                                                                                                    | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                              | Value                                                                                                                                                                                                       | Description                                                                                         |
| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-status` | `enum`- 'loading' \| 'loaded' \| 'error' | The loading status of the image.                                             |
| `data-avatar-fallback`                             | `''`                                                                                                                                                                                               | Present on the fallback element. |

----------------------------------------------------

# Button Documentation

A component that if passed a `href` prop will render an anchor element instead of a button element.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { Button } from "bits-ui";
</script>
<Button.Root
  class="rounded-input bg-dark text-background shadow-mini hover:bg-dark/95 inline-flex
 h-12 items-center justify-center px-[21px] text-[15px]
 font-semibold active:scale-[0.98] active:transition-all"
>
  Unlimited
</Button.Root>
```

## Structure

```svelte
<script lang="ts">
 import { Button } from "bits-ui";
</script>
<Button.Root />
```

## API Reference

### Button.Root

A component that can switch between a button and an anchor tag based on the `href`/`type` props.

| Property                                                              | Type                                                           | Description                                                                                                                                              |
| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `href` | `string`            | An optional prop that when passed converts the button into an anchor tag.`Default:  undefined`                          |
| `disabled`                          | `boolean`           | Whether or not the button is disabled. When disabled, the button cannot be interacted with.`Default: false`                |
| `ref` $bindable        | `HTMLButtonElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined` |
| `children`                          | `Snippet`           | The children content to render.`Default:  undefined`                                |

| Data Attribute                                   | Value         | Description                                                                                       |
| ----------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-button-root` | `''` | Present on the button element. |

----------------------------------------------------

# Calendar Documentation

Displays dates and days of the week, facilitating date-related interactions.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { Calendar } from "bits-ui";
  import CaretLeft from "phosphor-svelte/lib/CaretLeft";
  import CaretRight from "phosphor-svelte/lib/CaretRight";
  import { getLocalTimeZone, today } from "@internationalized/date";
  const isDateUnavailable: Calendar.RootProps["isDateUnavailable"] = (date) => {
    return date.day === 17 || date.day === 18;
  };
  let value = $state(today(getLocalTimeZone()));
</script>
<Calendar.Root
  class="border-dark-10 bg-background-alt shadow-card mt-6 rounded-[15px] border p-[22px]"
  {isDateUnavailable}
  weekdayFormat="short"
  fixedWeeks={true}
  type="single"
  bind:value
>
  {#snippet children({ months, weekdays })}
    <Calendar.Header class="flex items-center justify-between">
      <Calendar.PrevButton
        class="rounded-9px bg-background-alt hover:bg-muted inline-flex size-10 items-center justify-center active:scale-[0.98] active:transition-all"
      >
        <CaretLeft class="size-6" />
      </Calendar.PrevButton>
      <Calendar.Heading class="text-[15px] font-medium" />
      <Calendar.NextButton
        class="rounded-9px bg-background-alt hover:bg-muted inline-flex size-10 items-center justify-center active:scale-[0.98] active:transition-all"
      >
        <CaretRight class="size-6" />
      </Calendar.NextButton>
    </Calendar.Header>
    <div
      class="flex flex-col space-y-4 pt-4 sm:flex-row sm:space-x-4 sm:space-y-0"
    >
      {#each months as month, i (i)}
        <Calendar.Grid class="w-full border-collapse select-none space-y-1">
          <Calendar.GridHead>
            <Calendar.GridRow class="mb-1 flex w-full justify-between">
              {#each weekdays as day}
                <Calendar.HeadCell
                  class="text-muted-foreground font-normal! w-10 rounded-md text-xs"
                >
                  <div>{day.slice(0, 2)}</div>
                </Calendar.HeadCell>
              {/each}
            </Calendar.GridRow>
          </Calendar.GridHead>
          <Calendar.GridBody>
            {#each month.weeks as weekDates}
              <Calendar.GridRow class="flex w-full">
                {#each weekDates as date}
                  <Calendar.Cell
                    {date}
                    month={month.value}
                    class="p-0! relative size-10 text-center text-sm"
                  >
                    <Calendar.Day
                      class="rounded-9px text-foreground hover:border-foreground data-selected:bg-foreground data-disabled:text-foreground/30 data-selected:text-background data-unavailable:text-muted-foreground data-disabled:pointer-events-none data-outside-month:pointer-events-none data-selected:font-medium data-unavailable:line-through group relative inline-flex size-10 items-center justify-center whitespace-nowrap border border-transparent bg-transparent p-0 text-sm font-normal"
                    >
                      <div
                        class="bg-foreground group-data-selected:bg-background group-data-today:block absolute top-[5px] hidden size-1 rounded-full"
                      ></div>
                      {date.day}
                    </Calendar.Day>
                  </Calendar.Cell>
                {/each}
              </Calendar.GridRow>
            {/each}
          </Calendar.GridBody>
        </Calendar.Grid>
      {/each}
    </div>
  {/snippet}
</Calendar.Root>
```

##### Heads up!

Before diving into this component, it's important to understand how dates/times work in Bits UI. Please read the [Dates](/docs/dates) documentation to learn more!

## Structure

```svelte
<script lang="ts">
 import { Calendar } from "bits-ui";
</script>
<Calendar.Root>
 {#snippet children({ months, weekdays })}
  <Calendar.Header>
   <Calendar.PrevButton />
   <Calendar.Heading />
   <Calendar.NextButton />
  </Calendar.Header>
  {#each months as month}
   <Calendar.Grid>
    <Calendar.GridHead>
     <Calendar.GridRow>
      {#each weekdays as day}
       <Calendar.HeadCell>
        {day}
       </Calendar.HeadCell>
      {/each}
     </Calendar.GridRow>
    </Calendar.GridHead>
    <Calendar.GridBody>
     {#each month.weeks as weekDates}
      <Calendar.GridRow>
       {#each weekDates as date}
        <Calendar.Cell {date} month={month.value}>
         <Calendar.Day />
        </Calendar.Cell>
       {/each}
      </Calendar.GridRow>
     {/each}
    </Calendar.GridBody>
   </Calendar.Grid>
  {/each}
 {/snippet}
</Calendar.Root>
```

## Placeholder

The `placeholder` prop for the `Calendar.Root` component determines what date our calendar should start with when the user hasn't selected a date yet. It also determines the current "view" of the calendar.

As the user navigates through the calendar, the `placeholder` will be updated to reflect the currently focused date in that view.

By default, the `placeholder` will be set to the current date, and be of type `CalendarDate`.

## Managing Placeholder State

This section covers how to manage the `placeholder` state of the Calendar.

### Two-Way Binding

Use `bind:placeholder` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { Calendar } from "bits-ui";
 import { CalendarDateTime } from "@internationalized/date";
 let myPlaceholder = $state(new CalendarDateTime(2024, 8, 3, 12, 30));
</script>
<button onclick={() => (myPlaceholder = new CalendarDate(2024, 8, 3))}>
 Set placeholder to August 3rd, 2024
</button>
<Calendar.Root bind:placeholder={myPlaceholder}>
</Calendar.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { Calendar } from "bits-ui";
 import type { DateValue } from "@internationalized/date";
 let myPlaceholder = $state<DateValue>();
 function getPlaceholder() {
  return myPlaceholder;
 }
 function setPlaceholder(newPlaceholder: DateValue) {
  myPlaceholder = newPlaceholder;
 }
</script>
<Calendar.Root bind:placeholder={getPlaceholder, setPlaceholder}>
</Calendar.Root>
```

See the [State Management](/docs/state-management) documentation for more information.

## Managing Value State

This section covers how to manage the `value` state of the Calendar.

### Two-Way Binding

Use `bind:value` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { Calendar } from "bits-ui";
 import { CalendarDateTime } from "@internationalized/date";
 let myValue = $state(new CalendarDateTime(2024, 8, 3, 12, 30));
</script>
<button onclick={() => (myValue = myValue.add({ days: 1 }))}> Add 1 day </button>
<Calendar.Root type="single" bind:value={myValue}>
</Calendar.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { Calendar } from "bits-ui";
 import type { DateValue } from "@internationalized/date";
 let myValue = $state();
 function getValue() {
  return myValue;
 }
 function setValue(newValue: DateValue) {
  myValue = newValue;
 }
</script>
<Calendar.Root type="single" bind:value={getValue, setValue}>
</Calendar.Root>
```

See the [State Management](/docs/state-management) documentation for more information.

## Default Value

Often, you'll want to start the `Calendar.Root` component with a default value. Likely this value will come from a database in the format of an ISO 8601 string.

You can use the `parseDate` function from the `@internationalized/date` package to parse the string into a `CalendarDate` object.

```svelte
<script lang="ts">
 import { Calendar } from "bits-ui";
 import { parseDate } from "@internationalized/date";
 // this came from a database/API call
 const date = "2024-08-03";
 let value = $state(parseDate(date));
</script>
<Calendar.Root {value}>
</Calendar.Root>
```

## Validation

### Minimum Value

You can set a minimum value for the calendar by using the `minValue` prop on `Calendar.Root`. If a user selects a date that is less than the minimum value, the calendar will be marked as invalid.

```svelte
<script lang="ts">
 import { Calendar } from "bits-ui";
 import { today, getLocalTimeZone } from "@internationalized/date";
 const todayDate = today(getLocalTimeZone());
 const yesterday = todayDate.subtract({ days: 1 });
</script>
<Calendar.Root minValue={todayDate} value={yesterday}>
</Calendar.Root>
```

### Maximum Value

You can set a maximum value for the calendar by using the `maxValue` prop on `Calendar.Root`. If a user selects a date that is greater than the maximum value, the calendar will be marked as invalid.

```svelte
<script lang="ts">
 import { Calendar } from "bits-ui";
 import { today, getLocalTimeZone } from "@internationalized/date";
 const todayDate = today(getLocalTimeZone());
 const tomorrow = todayDate.add({ days: 1 });
</script>
<Calendar.Root maxValue={todayDate} value={tomorrow}>
</Calendar.Root>
```

### Unavailable Dates

You can specify specific dates that are unavailable for selection by using the `isDateUnavailable` prop. This prop accepts a function that returns a boolean value indicating whether a date is unavailable or not.

```svelte
<script lang="ts">
 import { Calendar } from "bits-ui";
 import { today, getLocalTimeZone, isNotNull } from "@internationalized/date";
 const todayDate = today(getLocalTimeZone());
 const tomorrow = todayDate.add({ days: 1 });
 function isDateUnavailable(date: DateValue) {
  return date.day === 1;
 }
</script>
<Calendar.Root {isDateUnavailable} value={tomorrow}>
</Calendar.Root>
```

### Disabled Dates

You can specify specific dates that are disabled for selection by using the `isDateDisabled` prop.

```svelte
<script lang="ts">
 import { Calendar } from "bits-ui";
 import { today, getLocalTimeZone, isNotNull } from "@internationalized/date";
 const todayDate = today(getLocalTimeZone());
 const tomorrow = todayDate.add({ days: 1 });
 function isDateDisabled(date: DateValue) {
  return date.day === 1;
 }
</script>
<Calendar.Root {isDateDisabled} value={tomorrow}>
</Calendar.Root>
```

## Appearance & Behavior

### Fixed Weeks

You can use the `fixedWeeks` prop to ensure that the calendar renders a fixed number of weeks, regardless of the number of days in the month. This is useful to keep the calendar visually consistent when the number of days in the month changes.

```svelte
<Calendar.Root fixedWeeks>
</Calendar.Root>
```

### Multiple Months

You can use the `numberOfMonths` prop to render multiple months at once.

```svelte
<Calendar.Root numberOfMonths={2}>
</Calendar.Root>
```

### Paged Navigation

By default, when the calendar has more than one month, the previous and next buttons will shift the calendar forward or backward by one month. However, you can change this behavior by setting the `pagedNavigation` prop to `true`, which will shift the calendar forward or backward by the number of months being displayed.

```svelte
<Calendar.Root pagedNavigation>
</Calendar.Root>
```

### Localization

The calendar will automatically format the content of the calendar according to the `locale` prop, which defaults to `'en-US'`, but can be changed to any locale supported by the [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) API.

```svelte
<Calendar.Root locale="fr-FR">
</Calendar.Root>
```

### Week Starts On

The calendar will automatically format the content of the calendar according to the `weekStartsOn` prop, which defaults to `0`, but can be changed to any day of the week, where `0` is Sunday and `6` is Saturday.

```svelte
<Calendar.Root weekStartsOn={1}>
</Calendar.Root>
```

### Multiple Selection

You can set the `type` prop to `'multiple'` to allow users to select multiple dates at once.

```svelte
<Calendar.Root type="multiple">
</Calendar.Root>
```

## Custom Composition

### Month Selector

The `Calendar` component includes a `PrevButton` and `NextButton` component to allow users to navigate between months. This is useful, but sometimes you may want to allow the user to select a specific month from a list of months, rather than having to navigate one at a time.

To achieve this, you can use the `placeholder` prop to set the month of the the calendar view programmatically.

```svelte
<script lang="ts">
 import { Calendar } from "bits-ui";
 import { CalendarDate } from "@internationalized/date";
 let placeholder = $state(new CalendarDate(2024, 8, 3));
</script>

<button
 onclick={() => {
  placeholder = placeholder.set({ month: 8 });
 }}
>
 Set month to August
</button>
<Calendar.Root bind:placeholder>
</Calendar.Root>
```

Updating the `placeholder` will update the calendar view to reflect the new month.

## API Reference

### Calendar.Root

The root calendar component which contains all other calendar components.

| Property                                                                                    | Type                                                                                                                                                                                                                                                                                                                                                     | Description                                                                                                                                                                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type` required | `enum`- 'single' \| 'multiple'                                                                                                                                                | Whether or not multiple dates can be selected.`Default:  undefined`                                                                                                                                                                     |
| `value` $bindable                            | `union`- DateValue \| DateValue\[]                                                                                                                                            | The selected date(s). If `type` is `'single'`, this will be a `DateValue`. If `type` is `'multiple'`, this will be an array of `DateValue`s.`Default:  undefined`                                                                       |
| `onValueChange`                                           | `function`- (value: DateValue) => void \| (value: DateValue\[]) => void                                                                                                       | A function that is called when the selected date changes.`Default:  undefined`                                                                                                                                                          |
| `placeholder`                                             | `DateValue`- import type { CalendarDate, CalendarDateTime, ZonedDateTime } from "@internationalized/date"; type DateValue = CalendarDate \| CalendarDateTime \| ZonedDateTime | The placeholder date, which is used to determine what month to display when no date is selected. This updates as the user navigates the calendar, and can be used to programmatically control the calendar's view.`Default:  undefined` |
| `onPlaceholderChange`                                     | `function`- (date: DateValue) => void                                                                                                                                         | A function that is called when the placeholder date changes.`Default:  undefined`                                                                                                                                                       |
| `pagedNavigation`                                         | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not to use paged navigation for the calendar. Paged navigation causes the previous and next buttons to navigate by the number of months displayed at once, rather than by one month.`Default: false`                            |
| `preventDeselect`                                         | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not to prevent the user from deselecting a date without selecting another date first.`Default: false`                                                                                                                           |
| `weekStartsOn`                                            | `number`                                                                                                                                                                                                                                                                                                      | The day of the week to start the calendar on. 0 is Sunday, 1 is Monday, etc.`Default: 0`                                                                                                                                                   |
| `weekdayFormat`                                           | `enum`- 'narrow' \| 'short' \| 'long'                                                                                                                                         | The format to use for the weekday strings provided via the `weekdays` slot prop.`Default: 'narrow'`                                                                                                                                        |
| `calendarLabel`                                           | `string`                                                                                                                                                                                                                                                                                                      | The accessible label for the calendar.`Default:  undefined`                                                                                                                                                                             |
| `fixedWeeks`                                              | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not to always display 6 weeks in the calendar.`Default: false`                                                                                                                                                                  |
| `isDateDisabled`                                          | `function`- (date: DateValue) => boolean                                                                                                                                      | A function that returns whether or not a date is disabled.`Default:  undefined`                                                                                                                                                         |
| `isDateUnavailable`                                       | `function`- (date: DateValue) => boolean                                                                                                                                      | A function that returns whether or not a date is unavailable.`Default:  undefined`                                                                                                                                                      |
| `maxValue`                                                | `DateValue`- import type { CalendarDate, CalendarDateTime, ZonedDateTime } from "@internationalized/date"; type DateValue = CalendarDate \| CalendarDateTime \| ZonedDateTime | The maximum date that can be selected.`Default:  undefined`                                                                                                                                                                             |
| `minValue`                                                | `DateValue`- import type { CalendarDate, CalendarDateTime, ZonedDateTime } from "@internationalized/date"; type DateValue = CalendarDate \| CalendarDateTime \| ZonedDateTime | The minimum date that can be selected.`Default:  undefined`                                                                                                                                                                             |
| `locale`                                                  | `string`                                                                                                                                                                                                                                                                                                      | The locale to use for formatting dates.`Default: 'en'`                                                                                                                                                                                     |
| `numberOfMonths`                                          | `number`                                                                                                                                                                                                                                                                                                      | The number of months to display at once.`Default: 1`                                                                                                                                                                                       |
| `disabled`                                                | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not the accordion is disabled.`Default: false`                                                                                                                                                                                  |
| `readonly`                                                | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not the calendar is readonly.`Default: false`                                                                                                                                                                                   |
| `initialFocus`                                            | `boolean`                                                                                                                                                                                                                                                                                                     | If `true`, the calendar will focus the selected day, today, or the first day of the month in that order depending on what is visible when the calendar is mounted.`Default: false`                                                         |
| `disableDaysOutsideMonth`                                 | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not to disable days outside the current month.`Default: false`                                                                                                                                                                  |
| `ref` $bindable                              | `HTMLDivElement`                                                                                                                                                                                                                                                                                              | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                 |
| `children`                                                | `Snippet`                                                                                                                                                                                                                                                                                                     | The children content to render.`Default:  undefined`                                                                                                                                                                                    |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };                                                                                                          | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                          | | Data Attribute                               | Value         | Description                                                                                     |
| ------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-invalid` | `''` | Present on the root element when the calendar is invalid.                |
| `data-disabled`                                     | `''` | Present on the root element when the calendar is disabled.               |
| `data-readonly`                                     | `''` | Present on the root element when the calendar is readonly.               |
| `data-calendar-root`                                | `''` | Present on the root element. |

### Calendar.Header

The header of the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLElement`                                                                                                                                                                                        | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                       |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the header element when the calendar is disabled.               |
| `data-readonly`                                      | `''` | Present on the header element when the calendar is readonly.               |
| `data-calendar-header`                               | `''` | Present on the header element. |

### Calendar.Heading

The heading of the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                        |
| -------------------------------------------------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the heading element when the calendar is disabled.               |
| `data-readonly`                                      | `''` | Present on the heading element when the calendar is readonly.               |
| `data-calendar-heading`                              | `''` | Present on the heading element. |

### Calendar.NextButton

The next button of the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                             |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the next button element when the calendar or this button is disabled. |
| `data-calendar-next-button`                          | `''` | Present on the next button element.  |

### Calendar.PrevButton

The previous button of the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                             |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the prev button element when the calendar or this button is disabled. |
| `data-calendar-prev-button`                          | `''` | Present on the prev button element.  |

### Calendar.Cell

A cell in the calendar grid.

| Property                                                              | Type                                                                                                                                                                                                                                                                                                                                                     | Description                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `date` | `DateValue`- import type { CalendarDate, CalendarDateTime, ZonedDateTime } from "@internationalized/date"; type DateValue = CalendarDate \| CalendarDateTime \| ZonedDateTime | The date for the cell.`Default:  undefined`                                                                                                                                    |
| `month`                             | `DateValue`- import type { CalendarDate, CalendarDateTime, ZonedDateTime } from "@internationalized/date"; type DateValue = CalendarDate \| CalendarDateTime \| ZonedDateTime | The current month the date is being displayed in.`Default:  undefined`                                                                                                         |
| `ref` $bindable        | `HTMLTableCellElement`                                                                                                                                                                                                                                                                                        | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                          | `Snippet`                                                                                                                                                                                                                                                                                                     | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                             | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };                                                                                                          | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                     |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present when the day is disabled.                                        |
| `data-unavailable`                                   | `''` | Present when the day is unavailable.                                     |
| `data-today`                                         | `''` | Present when the day is today.                                           |
| `data-outside-month`                                 | `''` | Present when the day is outside the current month.                       |
| `data-outside-visible-months`                        | `''` | Present when the day is outside the visible months.                      |
| `data-focused`                                       | `''` | Present when the day is focused.                                         |
| `data-selected`                                      | `''` | Present when the day is selected.                                        |
| `data-value`                                         | `''` | The date in the format "YYYY-MM-DD".                                     |
| `data-calendar-cell`                                 | `''` | Present on the cell element. |

### Calendar.Day

A day in the calendar grid.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                    |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present when the day is disabled.                                       |
| `data-unavailable`                                   | `''` | Present when the day is unavailable.                                    |
| `data-today`                                         | `''` | Present when the day is today.                                          |
| `data-outside-month`                                 | `''` | Present when the day is outside the current month.                      |
| `data-outside-visible-months`                        | `''` | Present when the day is outside the visible months.                     |
| `data-focused`                                       | `''` | Present when the day is focused.                                        |
| `data-selected`                                      | `''` | Present when the day is selected.                                       |
| `data-value`                                         | `''` | The date in the format "YYYY-MM-DD".                                    |
| `data-calendar-day`                                  | `''` | Present on the day element. |

### Calendar.Grid

The grid of dates in the calendar, typically representing a month.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLTableElement`                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                     |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the grid element when the calendar is disabled.               |
| `data-readonly`                                      | `''` | Present on the grid element when the calendar is readonly.               |
| `data-calendar-grid`                                 | `''` | Present on the grid element. |

### Calendar.GridBody

The body of the grid of dates in the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLTableSectionElement`                                                                                                                                                                            | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                          |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the grid element when the calendar is disabled.                    |
| `data-readonly`                                      | `''` | Present on the grid element when the calendar is readonly.                    |
| `data-calendar-grid-body`                            | `''` | Present on the grid body element. |

### Calendar.GridHead

The head of the grid of dates in the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLTableSectionElement`                                                                                                                                                                            | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                          |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the grid head element when the calendar is disabled.               |
| `data-readonly`                                      | `''` | Present on the grid head element when the calendar is readonly.               |
| `data-calendar-grid-head`                            | `''` | Present on the grid head element. |

### Calendar.GridRow

A row in the grid of dates in the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLTableRowElement`                                                                                                                                                                                | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                         |
| -------------------------------------------------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the grid row element when the calendar is disabled.               |
| `data-readonly`                                      | `''` | Present on the grid row element when the calendar is readonly.               |
| `data-calendar-grid-row`                             | `''` | Present on the grid row element. |

### Calendar.HeadCell

A cell in the head of the grid of dates in the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLTableCellElement`                                                                                                                                                                               | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                          |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the head cell element when the calendar is disabled.               |
| `data-readonly`                                      | `''` | Present on the head cell element when the calendar is readonly.               |
| `data-calendar-head-cell`                            | `''` | Present on the head cell element. |

----------------------------------------------------

# Checkbox Documentation

Allow users to switch between checked, unchecked, and indeterminate states.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { Checkbox, Label } from "bits-ui";
  import Check from "phosphor-svelte/lib/Check";
  import Minus from "phosphor-svelte/lib/Minus";
</script>
<div class="flex items-center space-x-3">
  <Checkbox.Root
    id="terms"
    aria-labelledby="terms-label"
    class="border-muted bg-foreground data-[state=unchecked]:border-border-input data-[state=unchecked]:bg-background data-[state=unchecked]:hover:border-dark-40 peer inline-flex size-[25px] items-center justify-center rounded-md border transition-all duration-150 ease-in-out active:scale-[0.98]"
    name="hello"
    indeterminate
  >
    {#snippet children({ checked, indeterminate })}
      <div class="text-background inline-flex items-center justify-center">
        {#if indeterminate}
          <Minus class="size-[15px]" weight="bold" />
        {:else if checked}
          <Check class="size-[15px]" weight="bold" />
        {/if}
      </div>
    {/snippet}
  </Checkbox.Root>
  <Label.Root
    id="terms-label"
    for="terms"
    class="text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70"
  >
    Accept terms and conditions
  </Label.Root>
</div>
```

## Overview

The Checkbox component provides a flexible and accessible way to create checkbox inputs in your Svelte applications. It supports three states: checked, unchecked, and indeterminate, allowing for complex form interactions and data representations.

## Key Features

- **Tri-State Support**: Handles checked, unchecked, and indeterminate states, providing versatility in form design.  
- **Accessibility**: Built with WAI-ARIA guidelines in mind, ensuring keyboard navigation and screen reader support.  
- **Flexible State Management**: Supports both controlled and uncontrolled state, allowing for full control over the checkbox's checked state. ## Architecture

The Checkbox component is composed of the following parts:

- **Root**: The main component that manages the state and behavior of the checkbox. ## Structure

Here's an overview of how the Checkbox component is structured in code:

```svelte
<script lang="ts">
 import { Checkbox } from "bits-ui";
</script>
<Checkbox.Root>
 {#snippet children({ checked, indeterminate })}
  {#if indeterminate}
   -
  {:else if checked}
   
  {:else}
   
  {/if}
 {/snippet}
</Checkbox.Root>
```

## Reusable Components

It's recommended to use the `Checkbox` primitive to create your own custom checkbox component that can be used throughout your application. In the example below, we're using the `Checkbox` and [`Label`](/docs/components/label) components to create a custom checkbox component.

MyCheckbox.svelte

```svelte
<script lang="ts">
 import { Checkbox, Label, useId, type WithoutChildrenOrChild } from "bits-ui";
 let {
  id = useId(),
  checked = $bindable(false),
  ref = $bindable(null),
  labelRef = $bindable(null),
  ...restProps
 }: WithoutChildrenOrChild<Checkbox.RootProps> & {
  labelText: string;
  labelRef?: HTMLLabelElement | null;
 } = $props();
</script>
<Checkbox.Root bind:checked bind:ref {...restProps}>
 {#snippet children({ checked, indeterminate })}
  {#if indeterminate}
   -
  {:else if checked}
   
  {:else}
   
  {/if}
 {/snippet}
</Checkbox.Root>
<Label.Root for={id} bind:ref={labelRef}>
 {labelText}
</Label.Root>
```

You can then use the `MyCheckbox` component in your application like so:

+page.svelte

```svelte
<script lang="ts">
 import MyCheckbox from "$lib/components/MyCheckbox.svelte";
</script>
<MyCheckbox labelText="Enable notifications" />
```

## Managing Checked State

This section covers how to manage the `checked` state of the Checkbox.

### Two-Way Binding

Use `bind:checked` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { Checkbox } from "bits-ui";
 let myChecked = $state(false);
</script>
<button onclick={() => (myChecked = false)}> uncheck </button>
<Checkbox.Root bind:checked={myChecked} />
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { Checkbox } from "bits-ui";
 let myChecked = $state(false);
 function getChecked() {
  return myChecked;
 }
 function setChecked(newChecked: boolean) {
  myChecked = newChecked;
 }
</script>
<Checkbox.Root bind:checked={getChecked, setChecked}>
</Checkbox.Root>
```

## Managing Indeterminate State

This section covers how to manage the `indeterminate` state of the Checkbox.

### Two-Way Binding

Use `bind:indeterminate` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import MyCheckbox from "$lib/components/MyCheckbox.svelte";
 let myIndeterminate = $state(true);
</script>
<button onclick={() => (myIndeterminate = false)}> clear indeterminate </button>
<MyCheckbox bind:indeterminate={myIndeterminate} />
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { Checkbox } from "bits-ui";
 let myIndeterminate = $state(true);
 function getIndeterminate() {
  return myIndeterminate;
 }
 function setIndeterminate(newIndeterminate: boolean) {
  myIndeterminate = newIndeterminate;
 }
</script>
<Checkbox.Root bind:indeterminate={getIndeterminate, setIndeterminate}>
</Checkbox.Root>
```

## Disabled State

You can disable the checkbox by setting the `disabled` prop to `true`.

```svelte
<MyCheckbox disabled labelText="Enable notifications" />
```

## HTML Forms

If you set the `name` prop, a hidden checkbox input will be rendered to submit the value of the checkbox with a form.

By default, the checkbox will be submitted with default checkbox value of `'on'` if the `checked` prop is `true`.

```svelte
<MyCheckbox name="notifications" labelText="Enable notifications" />
```

### Custom Input Value

If you'd prefer to submit a different value, you can use the `value` prop to set the value of the hidden input.

For example, if you wanted to submit a string value, you could do the following:

```svelte
<MyCheckbox value="hello" name="notifications" labelText="Enable notifications" />
```

### Required

If you want to make the checkbox required, you can use the `required` prop.

```svelte
<Checkbox.Root required>
</Checkbox.Root>
```

This will apply the `required` attribute to the hidden input element, ensuring that proper form submission is enforced.

## Checkbox Groups

You can use the `Checkbox.Group` component to create a checkbox group.

```svelte
<script lang="ts">
 import { Checkbox } from "bits-ui";
</script>
<Checkbox.Group name="notifications">
 <Checkbox.GroupLabel>Notifications</Checkbox.GroupLabel>
 <Checkbox.Root value="marketing" />
 <Checkbox.Root value="promotions" />
 <Checkbox.Root value="news" />
</Checkbox.Group>
```

```svelte
<script lang="ts">
  import { Checkbox, Label, useId } from "bits-ui";
  import Check from "phosphor-svelte/lib/Check";
  import Minus from "phosphor-svelte/lib/Minus";
  let myValue = $state<string[]>(["marketing", "news"]);
</script>
<Checkbox.Group
  class="flex flex-col gap-3"
  bind:value={myValue}
  name="notifications"
>
  <Checkbox.GroupLabel class="text-foreground-alt text-sm font-medium">
    Notifications
  </Checkbox.GroupLabel>
  <div class="flex flex-col gap-4">
    {@render MyCheckbox({ label: "Marketing", value: "marketing" })}
    {@render MyCheckbox({ label: "Promotions", value: "promotions" })}
    {@render MyCheckbox({ label: "News", value: "news" })}
    {@render MyCheckbox({ label: "Updates", value: "updates" })}
  </div>
</Checkbox.Group>
{#snippet MyCheckbox({ value, label }: { value: string; label: string })}
  {@const id = useId()}
  <div class="flex items-center">
    <Checkbox.Root
      {id}
      aria-labelledby="{id}-label"
      class="border-muted bg-foreground data-[state=unchecked]:border-border-input data-[state=unchecked]:bg-background data-[state=unchecked]:hover:border-dark-40 peer inline-flex size-[25px] items-center justify-center rounded-md border transition-all duration-150 ease-in-out active:scale-[0.98]"
      name="hello"
      {value}
    >
      {#snippet children({ checked, indeterminate })}
        <div class="text-background inline-flex items-center justify-center">
          {#if indeterminate}
            <Minus class="size-[15px]" weight="bold" />
          {:else if checked}
            <Check class="size-[15px]" weight="bold" />
          {/if}
        </div>
      {/snippet}
    </Checkbox.Root>
    <Label.Root
      id="{id}-label"
      for={id}
      class="pl-3 text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70"
    >
      {label}
    </Label.Root>
  </div>
{/snippet}
```

### Managing Value State

This section covers how to manage the `value` state of a Checkbox Group.

#### Two-Way Binding

Use `bind:value` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { Checkbox } from "bits-ui";
 let myValue = $state<string[]>([]);
</script>
<button
 onclick={() => {
  myValue = ["item-1", "item-2"];
 }}
>
 Open Items 1 and 2
</button>
<Checkbox.Group name="myItems" bind:value={myValue}>
 <Checkbox.GroupLabel>Items</Checkbox.GroupLabel>
 <Checkbox.Root value="item-1" />
 <Checkbox.Root value="item-2" />
 <Checkbox.Root value="item-3" />
</Checkbox.Group>
```

#### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { Checkbox } from "bits-ui";
 let myValue = $state<string[]>([]);
 function getValue() {
  return myValue;
 }
 function setValue(newValue: string[]) {
  myValue = newValue;
 }
</script>
<Checkbox.Group bind:value={getValue, setValue}>
</Checkbox.Group>
```

### HTML Forms

To render hidden `<input />` elements for the various checkboxes within a group, pass a `name` to `Checkbox.Group`. All descendent checkboxes will then render hidden inputs with the same name.

```svelte
<Checkbox.Group name="notifications">
</Checkbox.Group>
```

When a `Checkbox.Group` component is used, its descendent `Checkbox.Root` components will use certain properties from the group, such as the `name`, `required`, and `disabled`.

## API Reference

### Checkbox.Root

The button component used to toggle the state of the checkbox.

| Property                                                                                        | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `checked` $bindable | `boolean`                                                                                                                                                                                            | The checkbox button's checked state.`Default: false`                                                                                                                              |
| `onCheckedChange`                                             | `function`- (checked: boolean) => void                               | A callback that is fired when the checkbox button's checked state changes.`Default:  undefined`                                                                                |
| `indeterminate` $bindable                        | `boolean`                                                                                                                                                                                            | Whether the checkbox is an indeterminate state or not.`Default: false`                                                                                                            |
| `onIndeterminateChange`                                       | `function`- (indeterminate: boolean) => void                         | A callback that is fired when the indeterminate state changes.`Default:  undefined`                                                                                            |
| `disabled`                                                    | `boolean`                                                                                                                                                                                            | Whether or not the checkbox button is disabled. This prevents the user from interacting with it.`Default: false`                                                                  |
| `required`                                                    | `boolean`                                                                                                                                                                                            | Whether or not the checkbox is required.`Default: false`                                                                                                                          |
| `name`                                                        | `string`                                                                                                                                                                                             | The name of the checkbox. If provided a hidden input will be render to use for form submission. If not provided, the hidden input will not be rendered.`Default:  undefined`   |
| `value`                                                       | `string`                                                                                                                                                                                             | The value of the checkbox. This is what is submitted with the form when the checkbox is checked.`Default:  undefined`                                                          |
| `ref` $bindable                                  | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                    | `Snippet`- Snippet                                                   | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                       | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value                                                                                                                                                                                                                  | Description                                                                                     |
| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'checked' \| 'unchecked' \| 'indeterminate' | The checkbox's state of checked, unchecked, or indeterminate.            |
| `data-disabled`                                   | `''`                                                                                                                                                                                                          | Present when the checkbox is disabled.                                   |
| `data-checkbox-root`                              | `''`                                                                                                                                                                                                          | Present on the root element. |

### Checkbox.Group

A group that synchronizes its value state with its descendant checkboxes.

| Property                                                                                      | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                                                      |
| -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `value` $bindable | `string[]`                                                                                                                                                                                           | The value of the group. This is an array of the values of the checked checkboxes within the group.`Default: []`                                                                                                    |
| `onValueChange`                                             | `function`- (value: string\[]) => void                               | A callback that is fired when the checkbox group's value state changes.`Default:  undefined`                                                                                                                    |
| `disabled`                                                  | `boolean`                                                                                                                                                                                            | Whether or not the checkbox group is disabled. If `true`, all checkboxes within the group will be disabled. To disable a specific checkbox in the group, pass the `disabled` prop to the checkbox.`Default: false` |
| `required`                                                  | `boolean`                                                                                                                                                                                            | Whether or not the checkbox group is required for form submission.`Default: false`                                                                                                                                 |
| `name`                                                      | `string`                                                                                                                                                                                             | The name of the checkbox group. If provided a hidden input will be rendered to use for form submission.`Default:  undefined`                                                                                    |
| `ref` $bindable                                | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                         |
| `children`                                                  | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                                                            |
| `child`                                                     | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                  | | Data Attribute                                | Value         | Description                                                                                      |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-disabled` | `''` | Present when the checkbox group is disabled.                              |
| `data-checkbox-group`                                | `''` | Present on the group element. |

### Checkbox.GroupLabel

An accessible label for the checkbox group.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLLabelElement`                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                      |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-disabled` | `''` | Present when the checkbox group is disabled.                              |
| `data-checkbox-group-label`                          | `''` | Present on the label element. |

----------------------------------------------------

# Collapsible Documentation

Conceals or reveals content sections, enhancing space utilization and organization.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { Collapsible } from "bits-ui";
  import CaretUpDown from "phosphor-svelte/lib/CaretUpDown";
</script>
<Collapsible.Root class="w-[327px] space-y-3">
  <div class="flex items-center justify-between space-x-10">
    <h4 class="text-[15px] font-medium">@huntabyte starred 3 repositories</h4>
    <Collapsible.Trigger
      class="rounded-9px border-border-input bg-background-alt text-foreground shadow-btn hover:bg-muted inline-flex h-10 w-10 items-center justify-center border transition-all active:scale-[0.98]"
    >
      <CaretUpDown class="size-4 " weight="bold" />
      <span class="sr-only">Toggle</span>
    </Collapsible.Trigger>
  </div>
  <Collapsible.Content
    class="space-y-2 font-mono text-[15px] tracking-[0.01em]"
  >
    <div
      class="rounded-9px bg-muted inline-flex h-12 w-full items-center px-[18px] py-3"
    >
      @huntabyte/bits-ui
    </div>
    <div
      class="rounded-9px bg-muted inline-flex h-12 w-full items-center px-[18px] py-3"
    >
      @huntabyte/shadcn-svelte
    </div>
    <div
      class="rounded-9px bg-muted inline-flex h-12 w-full items-center px-[18px] py-3"
    >
      @svecosystem/runed
    </div>
  </Collapsible.Content>
</Collapsible.Root>
```

## Overview

The Collapsible component enables you to create expandable and collapsible content sections. It provides an efficient way to manage space and organize information in user interfaces, enabling users to show or hide content as needed.

## Key Features

- **Accessibility**: ARIA attributes for screen reader compatibility and keyboard navigation.  
- **Transition Support**: CSS variables and data attributes for smooth transitions between states.  
- **Flexible State Management**: Supports controlled and uncontrolled state, take control if needed.  
- **Compound Component Structure**: Provides a set of sub-components that work together to create a fully-featured collapsible. ## Architecture

The Collapsible component is composed of a few sub-components, each with a specific role:

- **Root**: The parent container that manages the state and context for the collapsible functionality.  
- **Trigger**: The interactive element (e.g., button) that toggles the expanded/collapsed state of the content.  
- **Content**: The container for the content that will be shown or hidden based on the collapsible state. ## Structure

Here's an overview of how the Collapsible component is structured in code:

```svelte
<script lang="ts">
 import { Collapsible } from "bits-ui";
</script>
<Collapsible.Root>
 <Collapsible.Trigger />
 <Collapsible.Content />
</Collapsible.Root>
```

## Reusable Components

It's recommended to use the `Collapsible` primitives to create your own custom collapsible component that can be used throughout your application.

MyCollapsible.svelte

```svelte
<script lang="ts">
 import { Collapsible, type WithoutChild } from "bits-ui";
 type Props = WithoutChild<Collapsible.RootProps> & {
  buttonText: string;
 };
 let {
  open = $bindable(false),
  ref = $bindable(null),
  buttonText,
  children,
  ...restProps
 }: Props = $props();
</script>
<Collapsible.Root bind:open bind:ref {...restProps}>
 <Collapsible.Trigger>{buttonText}</Collapsible.Trigger>
 <Collapsible.Content>
  {@render children?.()}
 </Collapsible.Content>
</Collapsible.Root>
```

You can then use the `MyCollapsible` component in your application like so:

+page.svelte

```svelte
<script lang="ts">
 import MyCollapsible from "$lib/components/MyCollapsible.svelte";
</script>
<MyCollapsible buttonText="Open Collapsible">Here is my collapsible content.</MyCollapsible>
```

## Managing Open State

This section covers how to manage the `open` state of the Collapsible.

### Two-Way Binding

Use `bind:open` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { Collapsible } from "bits-ui";
 let isOpen = $state(false);
</script>
<button onclick={() => (isOpen = true)}>Open Collapsible</button>
<Collapsible.Root bind:open={isOpen}>
</Collapsible.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { Collapsible } from "bits-ui";
 let myOpen = $state(false);
 function getOpen() {
  return myOpen;
 }
 function setOpen(newOpen: boolean) {
  myOpen = newOpen;
 }
</script>
<Collapsible.Root bind:open={getOpen, setOpen}>
</Collapsible.Root>
```

## Svelte Transitions

The Collapsible component can be enhanced with Svelte's built-in transition effects or other animation libraries.

### Using `forceMount` and `child` Snippets

To apply Svelte transitions to Collapsible components, use the `forceMount` prop in combination with the `child` snippet. This approach gives you full control over the mounting behavior and animation of the `Collapsible.Content`.

```svelte
<script lang="ts">
 import { Collapsible } from "bits-ui";
 import { fade } from "svelte/transition";
</script>
<Collapsible.Root>
 <Collapsible.Trigger>Open</Collapsible.Trigger>
 <Collapsible.Content forceMount>
  {#snippet child({ props, open })}
   {#if open}
    <div {...props} transition:fade>
    </div>
   {/if}
  {/snippet}
 </Collapsible.Content>
</Collapsible.Root>
```

In this example:

- The `forceMount` prop ensures the content is always in the DOM.
- The `child` snippet provides access to the open state and component props.
- Svelte's `#if` block controls when the content is visible.
- Transition directive ( `transition:fade` ) apply the animations.

### Best Practices

For cleaner code and better maintainability, consider creating custom reusable components that encapsulate this transition logic.

MyCollapsibleContent.svelte

```svelte
<script lang="ts">
 import { Collapsible, type WithoutChildrenOrChild } from "bits-ui";
 import { fade } from "svelte/transition";
 import type { Snippet } from "svelte";
 let {
  ref = $bindable(null),
  duration = 200,
  children,
  ...restProps
 }: WithoutChildrenOrChild<Collapsible.ContentProps> & {
  duration?: number;
  children?: Snippet;
 } = $props();
</script>
<Collapsible.Content forceMount bind:ref {...restProps}>
 {#snippet child({ props, open })}
  {#if open}
   <div {...props} transition:fade={{ duration }}>
    {@render children?.()}
   </div>
  {/if}
 {/snippet}
</Collapsible.Content>
```

You can then use the `MyCollapsibleContent` component alongside the other `Collapsible` primitives throughout your application:

```svelte
<script lang="ts">
 import { Collapsible } from "bits-ui";
 import { MyCollapsibleContent } from "$lib/components";
</script>
<Collapsible.Root>
 <Collapsible.Trigger>Open</Collapsible.Trigger>
 <MyCollapsibleContent duration={300}>
 </MyCollapsibleContent>
</Collapsible.Root>
```

## API Reference

### Collapsible.Root

The root collapsible container which manages the state of the collapsible.

| Property                                                                                     | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `open` $bindable | `boolean`                                                                                                                                                                                            | The open state of the collapsible. The content will be visible when this is true, and hidden when it's false.`Default: false`                                                     |
| `onOpenChange`                                             | `function`- (open: boolean) => void                                  | A callback that is fired when the collapsible's open state changes.`Default:  undefined`                                                                                       |
| `disabled`                                                 | `boolean`                                                                                                                                                                                            | Whether or not the collapsible is disabled. This prevents the user from interacting with it.`Default: false`                                                                      |
| `ref` $bindable                               | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                 | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                    | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                     |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | The collapsible's open state.                                            |
| `data-disabled`                                   | `''`                                                                                                                                                                                 | Present when the collapsible is disabled.                                |
| `data-collapsible-root`                           | `''`                                                                                                                                                                                 | Present on the root element. |

### Collapsible.Trigger

The button responsible for toggling the collapsible's open state.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                        |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | The collapsible's open state.                                               |
| `data-disabled`                                   | `''`                                                                                                                                                                                 | Present when the collapsible or this trigger is disabled.                   |
| `data-collapsible-trigger`                        | `''`                                                                                                                                                                                 | Present on the trigger element. |

### Collapsible.Content

The content displayed when the collapsible is open.

| Property                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `forceMount` | `boolean`                                                                                                                                                                                            | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                |
| `ref` $bindable              | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                | `Snippet`- Snippet                                                   | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                        |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | The collapsible's open state.                                               |
| `data-disabled`                                   | `''`                                                                                                                                                                                 | Present when the collapsible is disabled.                                   |
| `data-collapsible-content`                        | `''`                                                                                                                                                                                 | Present on the content element. |

| CSS Variable                                                      | Description                                                                                                      |
| ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--bits-collapsible-content-height` | The height of the collapsible content element.                                            |
| `--bits-collapsible-content-width`                                       | The width of the collapsible content element. |

----------------------------------------------------

# Combobox Documentation

Enables users to pick from a list of options displayed in a dropdown.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { Combobox } from "bits-ui";
  import CaretUpDown from "phosphor-svelte/lib/CaretUpDown";
  import Check from "phosphor-svelte/lib/Check";
  import OrangeSlice from "phosphor-svelte/lib/OrangeSlice";
  import CaretDoubleUp from "phosphor-svelte/lib/CaretDoubleUp";
  import CaretDoubleDown from "phosphor-svelte/lib/CaretDoubleDown";
  const fruits = [
    { value: "mango", label: "Mango" },
    { value: "watermelon", label: "Watermelon" },
    { value: "apple", label: "Apple" },
    { value: "pineapple", label: "Pineapple" },
    { value: "orange", label: "Orange" },
    { value: "grape", label: "Grape" },
    { value: "strawberry", label: "Strawberry" },
    { value: "banana", label: "Banana" },
    { value: "kiwi", label: "Kiwi" },
    { value: "peach", label: "Peach" },
    { value: "cherry", label: "Cherry" },
    { value: "blueberry", label: "Blueberry" },
    { value: "raspberry", label: "Raspberry" },
    { value: "blackberry", label: "Blackberry" },
    { value: "plum", label: "Plum" },
    { value: "apricot", label: "Apricot" },
    { value: "pear", label: "Pear" },
    { value: "grapefruit", label: "Grapefruit" }
  ];
  let searchValue = $state("");
  const filteredFruits = $derived(
    searchValue === ""
      ? fruits
      : fruits.filter((fruit) =>
          fruit.label.toLowerCase().includes(searchValue.toLowerCase())
        )
  );
</script>
<Combobox.Root
  type="multiple"
  name="favoriteFruit"
  onOpenChange={(o) => {
    if (!o) searchValue = "";
  }}
>
  <div class="relative">
    <OrangeSlice
      class="text-muted-foreground absolute start-3 top-1/2 size-6 -translate-y-1/2"
    />
    <Combobox.Input
      oninput={(e) => (searchValue = e.currentTarget.value)}
      class="h-input rounded-9px border-border-input bg-background placeholder:text-foreground-alt/50 focus:ring-foreground focus:ring-offset-background focus:outline-hidden inline-flex w-[296px] truncate border px-11 text-base transition-colors focus:ring-2 focus:ring-offset-2 sm:text-sm"
      placeholder="Search a fruit"
      aria-label="Search a fruit"
    />
    <Combobox.Trigger class="absolute end-3 top-1/2 size-6 -translate-y-1/2">
      <CaretUpDown class="text-muted-foreground size-6" />
    </Combobox.Trigger>
  </div>
  <Combobox.Portal>
    <Combobox.Content
      class="focus-override border-muted bg-background shadow-popover data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 outline-hidden z-50 h-96 max-h-[var(--bits-combobox-content-available-height)] w-[var(--bits-combobox-anchor-width)] min-w-[var(--bits-combobox-anchor-width)] select-none rounded-xl border px-1 py-3 data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1"
      sideOffset={10}
    >
      <Combobox.ScrollUpButton
        class="flex w-full items-center justify-center py-1"
      >
        <CaretDoubleUp class="size-3" />
      </Combobox.ScrollUpButton>
      <Combobox.Viewport class="p-1">
        {#each filteredFruits as fruit, i (i + fruit.value)}
          <Combobox.Item
            class="rounded-button data-highlighted:bg-muted outline-hidden flex h-10 w-full select-none items-center py-3 pl-5 pr-1.5 text-sm capitalize"
            value={fruit.value}
            label={fruit.label}
          >
            {#snippet children({ selected })}
              {fruit.label}
              {#if selected}
                <div class="ml-auto">
                  <Check />
                </div>
              {/if}
            {/snippet}
          </Combobox.Item>
        {:else}
          <span class="block px-5 py-2 text-sm text-muted-foreground">
            No results found, try again.
          </span>
        {/each}
      </Combobox.Viewport>
      <Combobox.ScrollDownButton
        class="flex w-full items-center justify-center py-1"
      >
        <CaretDoubleDown class="size-3" />
      </Combobox.ScrollDownButton>
    </Combobox.Content>
  </Combobox.Portal>
</Combobox.Root>
```

## Overview

The Combobox component combines the functionality of an input field with a dropdown list of selectable options. It provides users with the ability to search, filter, and select from a predefined set of choices.

## Key Features

- **Keyboard Navigation**: Full support for keyboard interactions, allowing users to navigate and select options without using a mouse.  
- **Customizable Rendering**: Flexible architecture for rendering options, including support for grouped items.  
- **Accessibility**: Built with ARIA attributes and keyboard interactions to ensure screen reader compatibility and accessibility standards.  
- **Portal Support**: Ability to render the dropdown content in a portal, preventing layout issues in complex UI structures. ## Architecture

The Combobox component is composed of several sub-components, each with a specific role:

- **Root**: The main container component that manages the state and context for the combobox.  
- **Input**: The input field that allows users to enter search queries.  
- **Trigger**: The button or element that opens the dropdown list.  
- **Portal**: Responsible for portalling the dropdown content to the body or a custom target.  
- **Group**: A container for grouped items, used to group related items.  
- **GroupHeading**: A heading for a group of items, providing a descriptive label for the group.  
- **Item**: An individual item within the list.  
- **Separator**: A visual separator between items.  
- **Content**: The dropdown container that displays the items. It uses [Floating UI](https://floating-ui.com/)
  to position the content relative to the trigger.
- **ContentStatic**: An alternative to the Content component, that enables you to opt-out of Floating UI and position the content yourself.  
- **Arrow**: An arrow element that points to the trigger when using the `Combobox.Content` component.

## Structure

Here's an overview of how the Combobox component is structured in code:

```svelte
<script lang="ts">
 import { Combobox } from "bits-ui";
</script>
<Combobox.Root>
 <Combobox.Input />
 <Combobox.Trigger />
 <Combobox.Portal>
  <Combobox.Content>
   <Combobox.Group>
    <Combobox.GroupHeading />
    <Combobox.Item />
   </Combobox.Group>
   <Combobox.Item />
  </Combobox.Content>
 </Combobox.Portal>
</Combobox.Root>
```

## Reusable Components

It's recommended to use the `Combobox` primitives to build your own custom combobox component that can be reused throughout your application.

CustomCombobox.svelte

```svelte
<script lang="ts">
 import { Combobox, type WithoutChildrenOrChild, mergeProps } from "bits-ui";
 type Item = { value: string; label: string };
 type Props = Combobox.RootProps & {
  items: Item[];
  inputProps?: WithoutChildrenOrChild<Combobox.InputProps>;
  contentProps?: WithoutChildrenOrChild<Combobox.ContentProps>;
 };
 let {
  items,
  value = $bindable(),
  open = $bindable(false),
  inputProps,
  contentProps,
  ...restProps
 }: Props = $props();
 let searchValue = $state("");
 const filteredItems = $derived.by(() => {
  if (searchValue === "") return items;
  return items.filter((item) => item.label.toLowerCase().includes(searchValue.toLowerCase()));
 });
 function handleInput(e: Event & { currentTarget: HTMLInputElement }) {
  searchValue = e.currentTarget.value;
 }
 function handleOpenChange(newOpen: boolean) {
  if (!newOpen) searchValue = "";
 }
 const mergedRootProps = $derived(mergeProps(restProps, { onOpenChange: handleOpenChange }));
 const mergedInputProps = $derived(mergeProps(inputProps, { oninput: handleInput }));
</script>
<Combobox.Root bind:value bind:open {...mergedRootProps}>
 <Combobox.Input {...mergedInputProps} />
 <Combobox.Trigger>Open</Combobox.Trigger>
 <Combobox.Portal>
  <Combobox.Content {...contentProps}>
   {#each filteredItems as item, i (i + item.value)}
    <Combobox.Item value={item.value} label={item.label}>
     {#snippet children({ selected })}
      {item.label}
      {selected ? "" : ""}
     {/snippet}
    </Combobox.Item>
   {:else}
    <span> No results found </span>
   {/each}
  </Combobox.Content>
 </Combobox.Portal>
</Combobox.Root>
```

+page.svelte

```svelte
<script lang="ts">
 import { CustomCombobox } from "$lib/components";
 const items = [
  { value: "mango", label: "Mango" },
  { value: "watermelon", label: "Watermelon" },
  { value: "apple", label: "Apple" },
  // ...
 ];
</script>
<CustomCombobox {items} />
```

## Managing Value State

This section covers how to manage the `value` state of the Combobox.

### Two-Way Binding

Use `bind:value` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { Combobox } from "bits-ui";
 let myValue = $state("");
</script>
<button onclick={() => (myValue = "A")}> Select A </button>
<Combobox.Root type="single" bind:value={myValue}>
</Combobox.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { Combobox } from "bits-ui";
 let myValue = $state("");
 function getValue() {
  return myValue;
 }
 function setValue(newValue: string) {
  myValue = newValue;
 }
</script>
<Combobox.Root type="single" bind:value={getValue, setValue}>
</Combobox.Root>
```

## Managing Open State

This section covers how to manage the `open` state of the Combobox.

### Two-Way Binding

Use `bind:open` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { Combobox } from "bits-ui";
 let myOpen = $state(false);
</script>
<button onclick={() => (myOpen = true)}> Open </button>
<Combobox.Root bind:open={myOpen}>
</Combobox.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { Combobox } from "bits-ui";
 let myOpen = $state(false);
 function getOpen() {
  return myOpen;
 }
 function setOpen(newOpen: boolean) {
  myOpen = newOpen;
 }
</script>
<Combobox.Root type="single" bind:open={getOpen, setOpen}>
</Combobox.Root>
```

## Opt-out of Floating UI

When you use the `Combobox.Content` component, Bits UI uses [Floating UI](https://floating-ui.com/) to position the content relative to the trigger, similar to other popover-like components.

You can opt-out of this behavior by instead using the `Combobox.ContentStatic` component.

```svelte
<Combobox.Root>
 <Combobox.Trigger />
 <Combobox.Input />
 <Combobox.Portal>
  <Combobox.ContentStatic>
   <Combobox.ScrollUpButton />
   <Combobox.Viewport>
    <Combobox.Item />
    <Combobox.Group>
     <Combobox.GroupHeading />
     <Combobox.Item />
    </Combobox.Group>
    <Combobox.ScrollDownButton />
   </Combobox.Viewport>
  </Combobox.ContentStatic>
 </Combobox.Portal>
</Combobox.Root>
```

When using this component, you'll need to handle the positioning of the content yourself. Keep in mind that using `Combobox.Portal` alongside `Combobox.ContentStatic` may result in some unexpected positioning behavior, feel free to not use the portal or work around it.

## Custom Anchor

By default, the `Combobox.Content` is anchored to the `Combobox.Input` component, which determines where the content is positioned.

If you wish to instead anchor the content to a different element, you can pass either a selector string or an `HTMLElement` to the `customAnchor` prop of the `Combobox.Content` component.

```svelte
<script lang="ts">
 import { Combobox } from "bits-ui";
 let customAnchor = $state<HTMLElement>(null!);
</script>
<div bind:this={customAnchor}></div>
<Combobox.Root>
 <Combobox.Trigger />
 <Combobox.Input />
 <Combobox.Content {customAnchor}>
 </Combobox.Content>
</Combobox.Root>
```

## What is the Viewport?

The `Combobox.Viewport` component is used to determine the size of the content in order to determine whether or not the scroll up and down buttons should be rendered.

If you wish to set a minimum/maximum height for the select content, you should apply it to the `Combobox.Viewport` component.

## Scroll Up/Down Buttons

The `Combobox.ScrollUpButton` and `Combobox.ScrollDownButton` components are used to render the scroll up and down buttons when the select content is larger than the viewport.

You must use the `Combobox.Viewport` component when using the scroll buttons.

## Native Scrolling/Overflow

If you don't want to use the scroll buttons and prefer to use the standard scrollbar/overflow behavior, you can omit the `Combobox.Scroll[Up|Down]Button` components and the `Combobox.Viewport` component.

You'll need to set a height on the `Combobox.Content` component and appropriate `overflow` styles to enable scrolling.

## Scroll Lock

By default, when a user opens the Combobox, scrolling outside the content will be disabled. You can override this behavior by setting the `preventScroll` prop to `false`.

```svelte
<Combobox.Content preventScroll={false}>
</Combobox.Content>
```

## Highlighted Items

The Combobox component follows the [WAI-ARIA descendant pattern](https://www.w3.org/TR/wai-aria-practices-1.2/#combobox) for highlighting items. This means that the `Combobox.Input` retains focus the entire time, even when navigating with the keyboard, and items are highlighted as the user navigates them.

### Styling Highlighted Items

You can use the `data-highlighted` attribute on the `Combobox.Item` component to style the item differently when it is highlighted.

### onHighlight / onUnhighlight

To trigger side effects when an item is highlighted or unhighlighted, you can use the `onHighlight` and `onUnhighlight` props.

```svelte
<Combobox.Item onHighlight={() => console.log('I am highlighted!')} onUnhighlight={() => console.log('I am unhighlighted!')} />

</Combobox.Item>
```

## Svelte Transitions

You can use the `forceMount` prop along with the `child` snippet to forcefully mount the `Combobox.Content` component to use Svelte Transitions or another animation library that requires more control.

```svelte
<script lang="ts">
 import { Combobox } from "bits-ui";
 import { fly } from "svelte/transition";
</script>
<Combobox.Content forceMount>
 {#snippet child({ wrapperProps, props, open })}
  {#if open}
   <div {...wrapperProps}>
    <div {...props} transition:fly>
    </div>
   </div>
  {/if}
 {/snippet}
</Combobox.Content>
```

Of course, this isn't the prettiest syntax, so it's recommended to create your own reusable content component that handles this logic if you intend to use this approach. For more information on using transitions with Bits UI components, see the [Transitions](/docs/transitions) documentation.

```svelte
<script lang="ts">
  import { Combobox } from "bits-ui";
  import CaretUpDown from "phosphor-svelte/lib/CaretUpDown";
  import Check from "phosphor-svelte/lib/Check";
  import OrangeSlice from "phosphor-svelte/lib/OrangeSlice";
  import CaretDoubleUp from "phosphor-svelte/lib/CaretDoubleUp";
  import CaretDoubleDown from "phosphor-svelte/lib/CaretDoubleDown";
  import { fly } from "svelte/transition";
  const fruits = [
    { value: "mango", label: "Mango" },
    { value: "watermelon", label: "Watermelon" },
    { value: "apple", label: "Apple" },
    { value: "pineapple", label: "Pineapple" },
    { value: "orange", label: "Orange" },
    { value: "grape", label: "Grape" },
    { value: "strawberry", label: "Strawberry" },
    { value: "banana", label: "Banana" },
    { value: "kiwi", label: "Kiwi" },
    { value: "peach", label: "Peach" },
    { value: "cherry", label: "Cherry" },
    { value: "blueberry", label: "Blueberry" },
    { value: "raspberry", label: "Raspberry" },
    { value: "blackberry", label: "Blackberry" },
    { value: "plum", label: "Plum" },
    { value: "apricot", label: "Apricot" },
    { value: "pear", label: "Pear" },
    { value: "grapefruit", label: "Grapefruit" }
  ];
  let searchValue = $state("");
  const filteredFruits = $derived(
    searchValue === ""
      ? fruits
      : fruits.filter((fruit) =>
          fruit.label.toLowerCase().includes(searchValue.toLowerCase())
        )
  );
</script>
<Combobox.Root
  type="single"
  name="favoriteFruit"
  onOpenChange={(o) => {
    if (!o) searchValue = "";
  }}
>
  <div class="relative">
    <OrangeSlice
      class="text-muted-foreground absolute start-3 top-1/2 size-6 -translate-y-1/2"
    />
    <Combobox.Input
      oninput={(e) => (searchValue = e.currentTarget.value)}
      class="h-input rounded-9px border-border-input bg-background placeholder:text-foreground-alt/50 focus:ring-foreground focus:ring-offset-background focus:outline-hidden inline-flex w-[296px] truncate border px-11 text-base transition-colors focus:ring-2 focus:ring-offset-2 sm:text-sm"
      placeholder="Search a fruit"
      aria-label="Search a fruit"
    />
    <Combobox.Trigger class="absolute end-3 top-1/2 size-6 -translate-y-1/2">
      <CaretUpDown class="text-muted-foreground size-6" />
    </Combobox.Trigger>
  </div>
  <Combobox.Portal>
    <Combobox.Content
      class="border-muted bg-background shadow-popover outline-hidden h-96 max-h-[var(--bits-combobox-content-available-height)] w-[var(--bits-combobox-anchor-width)] min-w-[var(--bits-combobox-anchor-width)] rounded-xl border px-1 py-3"
      sideOffset={10}
      forceMount
    >
      {#snippet child({ wrapperProps, props, open })}
        {#if open}
          <div {...wrapperProps}>
            <div {...props} transition:fly={{ duration: 300 }}>
              <Combobox.ScrollUpButton
                class="flex w-full items-center justify-center"
              >
                <CaretDoubleUp class="size-3" />
              </Combobox.ScrollUpButton>
              <Combobox.Viewport class="p-1">
                {#each filteredFruits as fruit, i (i + fruit.value)}
                  <Combobox.Item
                    class="rounded-button data-highlighted:bg-muted outline-hidden flex h-10 w-full select-none items-center py-3 pl-5 pr-1.5 text-sm  capitalize"
                    value={fruit.value}
                    label={fruit.label}
                  >
                    {#snippet children({ selected })}
                      {fruit.label}
                      {#if selected}
                        <div class="ml-auto">
                          <Check />
                        </div>
                      {/if}
                    {/snippet}
                  </Combobox.Item>
                {:else}
                  <span class="block px-5 py-2 text-sm text-muted-foreground">
                    No results found, try again.
                  </span>
                {/each}
              </Combobox.Viewport>
              <Combobox.ScrollDownButton
                class="flex w-full items-center justify-center"
              >
                <CaretDoubleDown class="size-3" />
              </Combobox.ScrollDownButton>
            </div>
          </div>
        {/if}
      {/snippet}
    </Combobox.Content>
  </Combobox.Portal>
</Combobox.Root>
```

## API Reference

### Combobox.Root

The root combobox component which manages & scopes the state of the combobox.

| Property                                                                                    | Type                                                                                                                                                                                                                                       | Description                                                                                                                                                                                                                                          |
| ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` required | `enum`- 'single' \| 'multiple'                                  | The type of combobox.`Default:  undefined`                                                                                                                                                                          |
| `value` $bindable                            | `union`- string \| string\[]                                    | The value of the combobox. When the type is `'single'`, this should be a string. When the type is `'multiple'`, this should be an array of strings.`Default:  undefined`                                            |
| `onValueChange`                                           | `function`- (string) => void \| (string\[]) => void             | A callback that is fired when the combobox value changes. When the type is `'single'`, the argument will be a string. When the type is `'multiple'`, the argument will be an array of strings.`Default:  undefined` |
| `open` $bindable                             | `boolean`                                                                                                                                                                                       | The open state of the combobox menu.`Default: false`                                                                                                                                                                   |
| `onOpenChange`                                            | `function`- (open: boolean) => void                             | A callback that is fired when the combobox menu's open state changes.`Default:  undefined`                                                                                                                          |
| `disabled`                                                | `boolean`                                                                                                                                                                                       | Whether or not the combobox component is disabled.`Default: false`                                                                                                                                                     |
| `name`                                                    | `string`                                                                                                                                                                                        | The name to apply to the hidden input element for form submission. If provided, a hidden input element will be rendered to submit the value of the combobox.`Default:  undefined`                                   |
| `required`                                                | `boolean`                                                                                                                                                                                       | Whether or not the combobox menu is required.`Default: false`                                                                                                                                                          |
| `scrollAlignment`                                         | `enum`- 'nearest' \| 'center'                                   | The alignment of the highlighted item when scrolling.`Default: 'nearest'`                                                                                                                                              |
| `loop`                                                    | `boolean`                                                                                                                                                                                       | Whether or not the combobox menu should loop through items.`Default: false`                                                                                                                                            |
| `allowDeselect`                                           | `boolean`                                                                                                                                                                                       | Whether or not the user can deselect the selected item by pressing it in a single select.`Default: true`                                                                                                               |
| `items`                                                   | `array`- { value: string; label: string; disabled?: boolean}\[] | Optionally provide an array of objects representing the items in the select for autofill capabilities. Only applicable to combobox's with type `single``Default:  undefined`                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                       | The children content to render.`Default:  undefined`                                                                                                                            |

### Combobox.Trigger

A button which toggles the combobox's open state.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                        |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | The combobox's open state.                                                  |
| `data-disabled`                                   | `''`                                                                                                                                                                                 | Present when the combobox is disabled.                                      |
| `data-combobox-trigger`                           | `''`                                                                                                                                                                                 | Present on the trigger element. |

### Combobox.Content

The element which contains the combobox's items.

| Property                                                              | Type                                                                                                                                                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `side` | `enum`- 'top' \| 'bottom' \| 'left' \| 'right'                                     | The preferred side of the anchor to render the floating element against when open. Will be reversed when collisions occur.`Default: bottom`                                                                                                                                                                                                                                                                                        |
| `sideOffset`                        | `number`                                                                                                                                                                                                           | The distance in pixels from the anchor to the floating element.`Default: 0`                                                                                                                                                                                                                                                                                                                                                        |
| `align`                             | `enum`- 'start' \| 'center' \| 'end'                                               | The preferred alignment of the anchor to render the floating element against when open. This may change when collisions occur.`Default: start`                                                                                                                                                                                                                                                                                     |
| `alignOffset`                       | `number`                                                                                                                                                                                                           | The distance in pixels from the anchor to the floating element.`Default: 0`                                                                                                                                                                                                                                                                                                                                                        |
| `arrowPadding`                      | `number`                                                                                                                                                                                                           | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0`                                                                                                                                                                                                                                                                                                  |
| `avoidCollisions`                   | `boolean`                                                                                                                                                                                                          | When `true`, overrides the `side` and `align` options to prevent collisions with the boundary edges.`Default: true`                                                                                                                                                                                                                                                                                                                |
| `collisionBoundary`                 | `union`- Element \| null                                                           | A boundary element or array of elements to check for collisions against.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                   |
| `collisionPadding`                  | `union`- number \| Partial\&lt;Record\&lt;Side, number\&gt;\&gt;                   | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0`                                                                                                                                                                                                                                                                                                  |
| `sticky`                            | `enum`- 'partial' \| 'always'                                                      | The sticky behavior on the align axis. `'partial'` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst `'always'` will keep the content in the boundary regardless.`Default: partial`                                                                                                                                                                                        |
| `hideWhenDetached`                  | `boolean`                                                                                                                                                                                                          | When `true`, hides the content when it is detached from the DOM. This is useful for when you want to hide the content when the user scrolls away.`Default: true`                                                                                                                                                                                                                                                                   |
| `updatePositionStrategy`            | `enum`- 'optimized' \| 'always'                                                    | The strategy to use when updating the position of the content. When `'optimized'` the content will only be repositioned when the trigger is in the viewport. When `'always'` the content will be repositioned whenever the position changes.`Default: optimized`                                                                                                                                                                   |
| `strategy`                          | `enum`- 'fixed' \| 'absolute'                                                      | The positioning strategy to use for the floating element. When `'fixed'` the element will be positioned relative to the viewport. When `'absolute'` the element will be positioned relative to the nearest positioned ancestor.`Default: fixed`                                                                                                                                                                                    |
| `preventScroll`                     | `boolean`                                                                                                                                                                                                          | When `true`, prevents the body from scrolling when the content is open. This is useful when you want to use the content as a modal.`Default: false`                                                                                                                                                                                                                                                                                |
| `customAnchor`                      | `union`- string \| HTMLElement \| Measurable \| null                               | Use an element other than the trigger to anchor the content to. If provided, the content will be anchored to the provided element instead of the trigger.`Default: null`                                                                                                                                                                                                                                                           |
| `onEscapeKeydown`                   | `function`- (event: KeyboardEvent) => void                                         | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default:  undefined`                                                                                                                                                                                                                    |
| `escapeKeydownBehavior`             | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` |
| `onInteractOutside`                 | `function`- (event: PointerEvent) => void                                          | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default:  undefined`                                                                                                                                                                                                        |
| `onFocusOutside`                    | `function`- (event: FocusEvent) => void                                            | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default:  undefined`                                                                                                                                                                                                                                                  |
| `interactOutsideBehavior`           | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close`  |
| `preventOverflowTextSelection`      | `boolean`                                                                                                                                                                                                          | When `true`, prevents the text selection from overflowing the bounds of the element.`Default: true`                                                                                                                                                                                                                                                                                                                                |
| `dir`                               | `enum`- 'ltr' \| 'rtl'                                                             | The reading direction of the app.`Default: 'ltr'`                                                                                                                                                                                                                                                                                                                                                                                  |
| `loop`                              | `boolean`                                                                                                                                                                                                          | Whether or not the combobox should loop through items when reaching the end.`Default: false`                                                                                                                                                                                                                                                                                                                                       |
| `forceMount`                        | `boolean`                                                                                                                                                                                                          | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                                                                                                                                                                                                                                                                 |
| `ref` $bindable        | `HTMLDivElement`                                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                                                                                                                                                                         |
| `children`                          | `Snippet`- Snippet                                                                 | The children content to render.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                                                            |
| `child`                             | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };               | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                                                                                                                                                                  | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                        |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | The combobox's open state.                                                  |
| `data-combobox-content`                           | `''`                                                                                                                                                                                 | Present on the content element. |

| CSS Variable                                                             | Description                                                                                                    |
| ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--bits-combobox-content-transform-origin` | The transform origin of the combobox content element.                                   |
| `--bits-combobox-content-available-width`                                       | The available width of the combobox content element.                                    |
| `--bits-combobox-content-available-height`                                      | The available height of the combobox content element.                                   |
| `--bits-combobox-anchor-width`                                                  | The width of the combobox trigger element.                                              |
| `--bits-combobox-anchor-height`                                                 | The height of the combobox trigger element. |

### Combobox.ContentStatic

The element which contains the combobox's items. (Static/No Floating UI)

| Property                                                                         | Type                                                                                                                                                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onEscapeKeydown` | `function`- (event: KeyboardEvent) => void                                         | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default:  undefined`                                                                                                                                                                                                                    |
| `escapeKeydownBehavior`                        | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` |
| `onInteractOutside`                            | `function`- (event: PointerEvent) => void                                          | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default:  undefined`                                                                                                                                                                                                        |
| `onFocusOutside`                               | `function`- (event: FocusEvent) => void                                            | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default:  undefined`                                                                                                                                                                                                                                                  |
| `interactOutsideBehavior`                      | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close`  |
| `onOpenAutoFocus`                              | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is opened. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `onCloseAutoFocus`                             | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is closed. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `trapFocus`                                    | `boolean`                                                                                                                                                                                                          | Whether or not to trap the focus within the content when open.`Default: true`                                                                                                                                                                                                                                                                                                                                                      |
| `preventScroll`                                | `boolean`                                                                                                                                                                                                          | When `true`, prevents the body from scrolling when the content is open. This is useful when you want to use the content as a modal.`Default: true`                                                                                                                                                                                                                                                                                 |
| `preventOverflowTextSelection`                 | `boolean`                                                                                                                                                                                                          | When `true`, prevents the text selection from overflowing the bounds of the element.`Default: true`                                                                                                                                                                                                                                                                                                                                |
| `dir`                                          | `enum`- 'ltr' \| 'rtl'                                                             | The reading direction of the app.`Default: 'ltr'`                                                                                                                                                                                                                                                                                                                                                                                  |
| `loop`                                         | `boolean`                                                                                                                                                                                                          | Whether or not the combobox should loop through items when reaching the end.`Default: false`                                                                                                                                                                                                                                                                                                                                       |
| `forceMount`                                   | `boolean`                                                                                                                                                                                                          | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                                                                                                                                                                                                                                                                 |
| `ref` $bindable                   | `HTMLDivElement`                                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                                                                                                                                                                         |
| `children`                                     | `Snippet`- Snippet                                                                 | The children content to render.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                                                            |
| `child`                                        | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };               | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                                                                                                                                                                  | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                        |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | The combobox's open state.                                                  |
| `data-combobox-content`                           | `''`                                                                                                                                                                                 | Present on the content element. |

### Combobox.Item

A combobox item, which must be a child of the `Combobox.Content` component.

| Property                                                                                     | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` required | `string`                                                                                                                                                                                             | The value of the item.`Default:  undefined`                                                                                                                                    |
| `label`                                                    | `string`                                                                                                                                                                                             | The label of the item, which is what the list will be filtered by.`Default:  undefined`                                                                                        |
| `disabled`                                                 | `boolean`                                                                                                                                                                                            | Whether or not the combobox item is disabled. This will prevent interaction/selection.`Default: false`                                                                            |
| `onHighlight`                                              | `function`- () => void                                               | A callback that is fired when the item is highlighted.`Default:  undefined`                                                                                                    |
| `onUnhighlight`                                            | `function`- () => void                                               | A callback that is fired when the item is unhighlighted.`Default:  undefined`                                                                                                  |
| `ref` $bindable                               | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                 | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                    | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value             | Description                                                                                                                |
| ----------------------------------------------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-value` | `string` | The value of the combobox item.                                                                     |
| `data-label`                                      | `string` | The label of the combobox item.                                                                     |
| `data-disabled`                                   | `''`     | Present when the item is disabled.                                                                  |
| `data-highlighted`                                | `''`     | Present when the item is highlighted, which is either via keyboard navigation of the menu or hover. |
| `data-selected`                                   | `''`     | Present when the item is selected.                                                                  |
| `data-combobox-item`                              | `''`     | Present on the item element.                            |

### Combobox.Input

A representation of the combobox input element, which is typically displayed in the content.

| Property                                                                      | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                                  |
| ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `defaultValue` | `string`                                                                                                                                                                                             | The default value of the input. This is not a reactive prop and is only used to populate the input when the combobox is first mounted if there is already a value set.`Default:  undefined` |
| `clearOnDeselect`                           | `boolean`                                                                                                                                                                                            | Whether to clear the input when the last item is deselected.`Default: false`                                                                                                                   |
| `ref` $bindable                | `HTMLInputElement`                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                     |
| `children`                                  | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                                        |
| `child`                                     | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`              | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                      |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-state` | `enum`- 'open' \| 'closed' | The combobox's open state.                                                |
| `data-disabled`                                   | `''`                                                                                                                                                                                 | Present when the combobox is disabled.                                    |
| `data-combobox-input`                             | `''`                                                                                                                                                                                 | Present on the input element. |

### Combobox.Group

A group of related combobox items.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                      | Value         | Description                                                                                      |
| -------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-combobox-group` | `''` | Present on the group element. |

### Combobox.GroupHeading

A heading for the parent combobox group. This is used to describe a group of related combobox items.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                              | Value         | Description                                                                                              |
| ---------------------------------------------------------------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-combobox-group-heading` | `''` | Present on the group heading element. |

### Combobox.Arrow

An optional arrow element which points to the content when open.

| Property                                                               | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `width` | `number`                                                                                                                                                                                             | The width of the arrow in pixels.`Default: 8`                                                                                                                                     |
| `height`                             | `number`                                                                                                                                                                                             | The height of the arrow in pixels.`Default: 8`                                                                                                                                    |
| `ref` $bindable         | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                           | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                              | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value         | Description                                                                                      |
| ----------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-arrow` | `''` | Present on the arrow element. |

----------------------------------------------------

# Command Documentation

A command menu component that can be used to search, filter, and select items.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { Command } from "bits-ui";
  import CalendarBlank from "phosphor-svelte/lib/CalendarBlank";
  import CodeBlock from "phosphor-svelte/lib/CodeBlock";
  import Palette from "phosphor-svelte/lib/Palette";
  import RadioButton from "phosphor-svelte/lib/RadioButton";
  import Sticker from "phosphor-svelte/lib/Sticker";
  import Textbox from "phosphor-svelte/lib/Textbox";
</script>
<Command.Root
  class="divide-border border-muted bg-background flex h-full w-full flex-col divide-y self-start overflow-hidden rounded-xl border"
>
  <Command.Input
    class="focus-override h-input placeholder:text-foreground-alt/50 focus:outline-hidden bg-background inline-flex truncate rounded-xl px-4 text-sm transition-colors focus:ring-0"
    placeholder="Search for something..."
  />
  <Command.List
    class="max-h-[280px] overflow-y-auto overflow-x-hidden px-2 pb-2"
  >
    <Command.Viewport>
      <Command.Empty
        class="text-muted-foreground flex w-full items-center justify-center pb-6 pt-8 text-sm"
      >
        No results found.
      </Command.Empty>
      <Command.Group>
        <Command.GroupHeading
          class="text-muted-foreground px-3 pb-2 pt-4 text-xs"
        >
          Suggestions
        </Command.GroupHeading>
        <Command.GroupItems>
          <Command.Item
            class="rounded-button data-selected:bg-muted outline-hidden flex h-10 cursor-pointer select-none items-center gap-2 px-3 py-2.5 text-sm capitalize"
            keywords={["getting started", "tutorial"]}
          >
            <Sticker class="size-4" />
            Introduction
          </Command.Item>
          <Command.Item
            class="rounded-button data-selected:bg-muted outline-hidden flex h-10 cursor-pointer select-none items-center gap-2 px-3 py-2.5 text-sm capitalize"
            keywords={["child", "custom element", "snippets"]}
          >
            <CodeBlock class="size-4 " />
            Delegation
          </Command.Item>
          <Command.Item
            class="rounded-button data-selected:bg-muted outline-hidden flex h-10 cursor-pointer select-none items-center gap-2 px-3 py-2.5 text-sm capitalize"
            keywords={["css", "theme", "colors", "fonts", "tailwind"]}
          >
            <Palette class="size-4" />
            Styling
          </Command.Item>
        </Command.GroupItems>
      </Command.Group>
      <Command.Separator />
      <Command.Group>
        <Command.GroupHeading
          class="text-muted-foreground px-3 pb-2 pt-4 text-xs"
        >
          Components
        </Command.GroupHeading>
        <Command.GroupItems>
          <Command.Item
            class="rounded-button data-selected:bg-muted outline-hidden flex h-10 cursor-pointer select-none items-center gap-2 px-3 py-2.5 text-sm capitalize"
            keywords={["dates", "times"]}
          >
            <CalendarBlank class="size-4" />
            Calendar
          </Command.Item>
          <Command.Item
            class="rounded-button data-selected:bg-muted outline-hidden flex h-10 cursor-pointer select-none items-center gap-2 px-3 py-2.5 text-sm capitalize"
            keywords={["buttons", "forms"]}
          >
            <RadioButton class="size-4" />
            Radio Group
          </Command.Item>
          <Command.Item
            class="rounded-button data-selected:bg-muted outline-hidden flex h-10 cursor-pointer select-none items-center gap-2 px-3 py-2.5 text-sm capitalize"
            keywords={["inputs", "text", "autocomplete"]}
          >
            <Textbox class="size-4" />
            Combobox
          </Command.Item>
        </Command.GroupItems>
      </Command.Group>
    </Command.Viewport>
  </Command.List>
</Command.Root>
```

## Overview

The Command component, also known as a command menu, is designed to provide users with a quick and efficient way to search, filter, and select items within an application. It combines the functionality of a search input with a dynamic, filterable list of commands or options, making it ideal for applications that require fast navigation or action execution.

## Key Features

- **Dynamic Filtering**: As users type in the input field, the list of commands or items is instantly filtered and sorted based on an (overridable) scoring algorithm.  
- **Keyboard Navigation**: Full support for keyboard interactions, allowing users to quickly navigate and select items without using a mouse.  
- **Grouped Commands**: Ability to organize commands into logical groups, enhancing readability and organization.  
- **Empty and Loading States**: Built-in components to handle scenarios where no results are found or when results are being loaded.  
- **Accessibility**: Designed with ARIA attributes and keyboard interactions to ensure screen reader compatibility and accessibility standards. ## Architecture

The Command component is composed of several sub-components, each with a specific role:

- **Root**: The main container that manages the overall state and context of the command menu.  
- **Input**: The text input field where users can type to search or filter commands.  
- **List**: The container for the list of commands or items.  
- **Viewport**: The visible area of the command list, which applies CSS variables to handle dynamic resizing/animations based on the height of the list.  
- **Empty**: A component to display when no results are found.  
- **Loading**: A component to display while results are being fetched or processed.  
- **Group**: A container for a group of items within the command menu.  
- **GroupHeading**: A header element to provide an accessible label for a group of items.  
- **GroupItems**: A container for the items within a group.  
- **Item**: Individual selectable command or item.  
- **LinkItem**: A variant of `Command.Item` specifically for link-based actions.
- **Separator**: A visual separator to divide different sections of the command list. ## Structure

Here's an overview of how the Command component is structured in code:

```svelte
<script lang="ts">
 import { Command } from "bits-ui";
</script>
<Command.Root>
 <Combobox.Input />
 <Command.List>
  <Command.Viewport>
   <Command.Empty />
   <Command.Loading />
   <Command.Group>
    <Command.GroupHeading />
    <Command.GroupItems>
     <Command.Item />
     <Command.LinkItem />
    </Command.GroupItems>
   </Command.Group>
   <Command.Separator />
   <Command.Item />
   <Command.LinkItem />
  </Command.Viewport>
 </Command.List>
</Command.Root>
```

## Managing Value State

Bits UI offers several approaches to manage and synchronize the Command's value state, catering to different levels of control and integration needs.

### 1. Two-Way Binding

For seamless state synchronization, use Svelte's `bind:value` directive. This method automatically keeps your local state in sync with the component's internal state.

```svelte
<script lang="ts">
 import { Command } from "bits-ui";
 let myValue = $state("");
</script>
<button onclick={() => (myValue = "A")}> Select A </button>
<Command.Root bind:value={myValue}>
</Command.Root>
```

#### Key Benefits

- Simplifies state management  
- Automatically updates `myValue` when the internal state changes (e.g., via clicking on an item)
- Allows external control (e.g., selecting an item via a separate button) ### 2. Change Handler

To perform additional logic on state changes, use the `onValueChange` prop. This approach is useful when you need to execute side effects when the value changes.

```svelte
<script lang="ts">
 import { Command } from "bits-ui";
</script>
<Command.Root
 onValueChange={(value) => {
  // do something with the new value
  console.log(value);
 }}
>
</Command.Root>
```

#### Use Cases

- Implementing custom behaviors on value change  
- Integrating with external state management solutions  
- Triggering side effects (e.g., logging, data fetching) ### 3. Fully Controlled

For complete control over the component's state, use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) to manage the value state externally. You pass a getter function and a setter function to the `bind:value` directive, giving you full control over how the value is updated/retrieved.

```svelte
<script lang="ts">
 import { Command } from "bits-ui";
 let myValue = $state("");
</script>
<Command.Root bind:value={() => myValue, (newValue) => (myValue = newValue)}>
</Command.Root>
```

#### When to Use

- Implementing complex value change logic  
- Coordinating multiple UI elements  
- Debugging state-related issues ##### Note

While powerful, fully controlled state should be used judiciously as it increases complexity and can cause unexpected behaviors if not handled carefully.

For more in-depth information on controlled components and advanced state management techniques, refer to our [State Management](/docs/state-management) documentation.

## In a Modal

You can combine the `Command` component with the `Dialog` component to display the command menu within a modal.

```svelte
<script lang="ts">
  import { Command, Dialog } from "bits-ui";
  import CalendarBlank from "phosphor-svelte/lib/CalendarBlank";
  import CodeBlock from "phosphor-svelte/lib/CodeBlock";
  import Palette from "phosphor-svelte/lib/Palette";
  import RadioButton from "phosphor-svelte/lib/RadioButton";
  import Sticker from "phosphor-svelte/lib/Sticker";
  import Textbox from "phosphor-svelte/lib/Textbox";
  let dialogOpen = $state(false);
  function handleKeydown(e: KeyboardEvent) {
    if (e.key === "j" && (e.metaKey || e.ctrlKey)) {
      e.preventDefault();
      dialogOpen = true;
    }
  }
</script>
<svelte:document onkeydown={handleKeydown} />
<Dialog.Root bind:open={dialogOpen}>
  <Dialog.Trigger
    class="rounded-input bg-dark text-background
 shadow-mini hover:bg-dark/95 focus-visible:ring-foreground focus-visible:ring-offset-background focus-visible:outline-hidden inline-flex
 h-12 select-none items-center justify-center whitespace-nowrap px-[21px] text-[15px] font-semibold transition-colors focus-visible:ring-2 focus-visible:ring-offset-2 active:scale-[0.98]"
  >
    Open Command Menu J
  </Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay
      class="data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 fixed inset-0 z-50 bg-black/80"
    />
    <Dialog.Content
      class="rounded-card-lg bg-background shadow-popover data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95  data-[state=closed]:slide-out-to-left-1/2 data-[state=closed]:slide-out-to-top-[48%] data-[state=open]:slide-in-from-left-1/2 data-[state=open]:slide-in-from-top-[48%] outline-hidden fixed left-[50%] top-[50%] z-50 w-full max-w-[94%] translate-x-[-50%] translate-y-[-50%] sm:max-w-[490px] md:w-full"
    >
      <Dialog.Title class="sr-only">Command Menu</Dialog.Title>
      <Dialog.Description class="sr-only">
        This is the command menu. Use the arrow keys to navigate and press K to
        open the search bar.
      </Dialog.Description>
      <Command.Root
        class="divide-border border-muted bg-background flex h-full w-full flex-col divide-y self-start overflow-hidden rounded-xl border"
      >
        <Command.Input
          class="focus-override h-input bg-background placeholder:text-foreground-alt/50 focus:outline-hidden inline-flex truncate rounded-xl px-4 text-sm transition-colors focus:ring-0"
          placeholder="Search for something..."
        />
        <Command.List
          class="max-h-[280px] overflow-y-auto overflow-x-hidden px-2 pb-2"
        >
          <Command.Viewport>
            <Command.Empty
              class="text-muted-foreground flex w-full items-center justify-center pb-6 pt-8 text-sm"
            >
              No results found.
            </Command.Empty>
            <Command.Group>
              <Command.GroupHeading
                class="text-muted-foreground px-3 pb-2 pt-4 text-xs"
              >
                Suggestions
              </Command.GroupHeading>
              <Command.GroupItems>
                <Command.Item
                  class="rounded-button data-selected:bg-muted outline-hidden flex h-10 cursor-pointer select-none items-center gap-2 px-3 py-2.5 text-sm capitalize"
                  keywords={["getting started", "tutorial"]}
                >
                  <Sticker class="size-4" />
                  Introduction
                </Command.Item>
                <Command.Item
                  class="rounded-button data-selected:bg-muted outline-hidden flex h-10 cursor-pointer select-none items-center gap-2 px-3 py-2.5 text-sm capitalize"
                  keywords={["child", "custom element", "snippets"]}
                >
                  <CodeBlock class="size-4 " />
                  Delegation
                </Command.Item>
                <Command.Item
                  class="rounded-button data-selected:bg-muted outline-hidden flex h-10 cursor-pointer select-none items-center gap-2 px-3 py-2.5 text-sm capitalize"
                  keywords={["css", "theme", "colors", "fonts", "tailwind"]}
                >
                  <Palette class="size-4" />
                  Styling
                </Command.Item>
              </Command.GroupItems>
            </Command.Group>
            <Command.Separator />
            <Command.Group>
              <Command.GroupHeading
                class="text-muted-foreground px-3 pb-2 pt-4 text-xs"
              >
                Components
              </Command.GroupHeading>
              <Command.GroupItems>
                <Command.Item
                  class="rounded-button data-selected:bg-muted outline-hidden flex h-10 cursor-pointer select-none items-center gap-2 px-3 py-2.5 text-sm capitalize"
                  keywords={["dates", "times"]}
                >
                  <CalendarBlank class="size-4" />
                  Calendar
                </Command.Item>
                <Command.Item
                  class="rounded-button data-selected:bg-muted outline-hidden flex h-10 cursor-pointer select-none items-center gap-2 px-3 py-2.5 text-sm capitalize"
                  keywords={["buttons", "forms"]}
                >
                  <RadioButton class="size-4" />
                  Radio Group
                </Command.Item>
                <Command.Item
                  class="rounded-button data-selected:bg-muted outline-hidden flex h-10 cursor-pointer select-none items-center gap-2 px-3 py-2.5 text-sm capitalize"
                  keywords={["inputs", "text", "autocomplete"]}
                >
                  <Textbox class="size-4" />
                  Combobox
                </Command.Item>
              </Command.GroupItems>
            </Command.Group>
          </Command.Viewport>
        </Command.List>
      </Command.Root>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog.Root>
```

## Filtering

### Custom Filter

By default, the `Command` component uses a scoring algorithm to determine how the items should be sorted/filtered. You can provide a custom filter function to override this behavior.

The function should return a number between `0` and `1`, with `1` being a perfect match, and `0` being no match, resulting in the item being hidden entirely.

The following example shows how you might implement a strict substring match filter:

```svelte
<script lang="ts">
 import { Command } from "bits-ui";
 function customFilter(
  commandValue: string,
  search: string,
  commandKeywords?: string[]
 ): number {
  return commandValue.includes(search) ? 1 : 0;
 }
</script>
<Command.Root filter={customFilter}>
</Command.Root>
```

### Extend Default Filter

By default, the `Command` component uses the `computeCommandScore` function to determine the score of each item and filters/sorts them accordingly. This function is exported for you to use and extend as needed.

```svelte
<script lang="ts">
 import { Command, computeCommandScore } from "bits-ui";
 function customFilter(
  commandValue: string,
  search: string,
  commandKeywords?: string[]
 ): number {
  const score = computeCommandScore(commandValue, search, commandKeywords);
  // Add custom logic here
  return score;
 }
</script>
<Command.Root filter={customFilter}>
</Command.Root>
```

### Disable Filtering

You can disable filtering by setting the `shouldFilter` prop to `false`.

```svelte
<Command.Root shouldFilter={false}>
</Command.Root>
```

This is useful when you have a lot of custom logic, need to fetch items asynchronously, or just want to handle filtering yourself. You'll be responsible for iterating over the items and determining which ones should be shown.

## Item Selection

You can use the `onSelect` prop to handle the selection of items.

```svelte
<Command.Item onSelect={() => console.log("selected something!")} />
```

## Links

If you want one of the items to get all the benefits of a link (prefetching, etc.), you should use the `Command.LinkItem` component instead of the `Command.Item` component. The only difference is that the `Command.LinkItem` component will render an `a` element instead of a `div` element.

```svelte
<Command.LinkItem href="/some/path">
</Command.LinkItem>
```

## Imperative API

For more advanced use cases, such as custom keybindings, the `Command.Root` component exposes several methods for programmatic control.

Access these by binding to the component:

```svelte
<script lang="ts">
 import { Command } from "bits-ui";
 let command: typeof Command.Root;
</script>
<Command.Root bind:this={command}>
</Command.Root>
```

### Methods

#### `getValidItems()` Returns an array of valid (non-disabled, visible) command items. Useful for checking bounds before operations.

```ts
const items = command.getValidItems();
console.log(items.length); // number of selectable items
```

#### `updateSelectedToIndex(index: number)` Sets selection to item at specified index. No-op if index is invalid.

```ts
// select third item (if it exists)
command.updateSelectedToIndex(2);
// with bounds check
const items = command.getValidItems();
if (index < items.length) {
 command.updateSelectedToIndex(index);
}
```

#### `updateSelectedByGroup(change: 1 | -1)` Moves selection to first item in next/previous group. Falls back to next/previous item if no group found.

```ts
command.updateSelectedByGroup(1); // move to next group
command.updateSelectedByGroup(-1); // move to previous group
```

#### `updateSelectedByItem(change: 1 | -1)` Moves selection up/down relative to current item. Wraps around if `loop` option enabled.

```ts
command.updateSelectedByItem(1); // next item
command.updateSelectedByItem(-1); // previous item
```

### Usage Example

```svelte
<script lang="ts">
 import { Command } from "bits-ui";
 let command: typeof Command.Root;
 function jumpToLastItem() {
  if (!command) return;
  const items = command.getValidItems();
  if (!items.length) return;
  command.updateSelectedToIndex(items.length - 1); }
</script>
<svelte:window
 onkeydown={(e) => {
  if (e.key === "o") {
   jumpToLastItem();
  }
 }}
/>
<Command.Root bind:this={command}>
</Command.Root>
```

## API Reference

### Command.Root

The main container that manages the overall state and context of the component.

| Property                                                                                      | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Description                                                                                                                                                                                                                                                                                                                      |
| -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` $bindable | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | The value of the command.`Default:  undefined`                                                                                                                                                                                                                                                  |
| `onValueChange`                                             | `function`- (value: string) => void                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | A callback that is fired when the command value changes.`Default:  undefined`                                                                                                                                                                                                                   |
| `label`                                                     | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | An accessible label for the command menu. This is not visible and is only used for screen readers.`Default:  undefined`                                                                                                                                                                         |
| `filter`                                                    | `function`- (value: string, search: string, keywords?: string\[]) => number;                                                                                                                                                                                                                                                                                                                                                                                                                             | A custom filter function used to filter items. This function should return a number between `0` and `1`, with `1` being a perfect match, and `0` being no match, resulting in the item being hidden entirely. The items are sorted/filtered based on this score.`Default:  undefined`           |
| `shouldFilter`                                              | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Whether or not the command menu should filter items. This is useful when you want to apply custom filtering logic outside of the Command component.`Default: true`                                                                                                                                 |
| `onStateChange`                                             | `function`- type CommandState = { /\*\* The value of the search query \*/ search: string; /\*\* The value of the selected command menu item \*/ value: string; /\*\* The filtered items \*/ filtered: { /\*\* The count of all visible items. \*/ count: number; /\*\* Map from visible item id to its search store. \*/ items: Map\<string, number>; /\*\* Set of groups with at least one visible item. \*/ groups: Set\<string>; }; }; type onStateChange = (state: Readonly\<CommandState>) => void; | A callback that fires when the command's internal state changes. This callback receives a readonly snapshot of the current state. The callback is debounced and only fires once per batch of related updates (e.g., when typing triggers filtering and selection changes).`Default:  undefined` |
| `loop`                                                      | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Whether or not the command menu should loop through items when navigating with the keyboard.`Default: false`                                                                                                                                                                                       |
| `disablePointerSelection`                                   | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Set this to true to prevent items from being selected when the users pointer moves over them.`Default: false`                                                                                                                                                                                      |
| `vimBindings`                                               | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Whether VIM bindings should be enabled or not, which allow the user to navigate using ctrl+n/j/p/k`Default: true`                                                                                                                                                                                  |
| `ref` $bindable                                | `HTMLDivElement`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                                         |
| `children`                                                  | `Snippet`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | The children content to render.`Default:  undefined`                                                                                                                                                                                                                                            |
| `child`                                                     | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };                                                                                                                                                                                                                                                                                                                                                                                                                                     | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                                  | | Data Attribute                                    | Value         | Description                                                                                     |
| ------------------------------------------------------------------------------------ | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-command-root` | `''` | Present on the root element. |

### Command.Input

The text input field where users can type to search or filter commands.

| Property                                                                                      | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` $bindable | `string`                                                                                                                                                                                             | The value of the search query. This is used to filter items and to search for items.`Default:  undefined`                                                                      |
| `ref` $bindable                                | `HTMLInputElement`                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                  | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                     | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                     | Value         | Description                                                                                      |
| ------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-command-input` | `''` | Present on the input element. |

### Command.List

The container for the viewport, items, and other elements of the command menu.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                    | Value         | Description                                                                                     |
| ------------------------------------------------------------------------------------ | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-command-list` | `''` | Present on the list element. |

| CSS Variable                                               | Description                                                                                                                                                       |
| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--bits-command-list-height` | The height of the command list element, which is computed by the `Command.Viewport` component. |

### Command.Viewport

The visible area of the command list, which applies CSS variables to handle dynamic resizing/animations based on the height of the list.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                        | Value         | Description                                                                                         |
| ---------------------------------------------------------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-command-viewport` | `''` | Present on the viewport element. |

### Command.Group

A container for a group of items within the command menu.

| Property                                                               | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                                                                                                 |
| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` | `string`                                                                                                                                                                                             | If a `Command.GroupHeading` is used within this group, the contents of the heading will be used as the value. If the content is dynamic or you wish to have a more specific value, you can provide a unique value for the group here.`Default:  undefined` |
| `forceMount`                         | `boolean`                                                                                                                                                                                            | Whether or not the group should always be mounted to the DOM, regardless of the internal filtering logic`Default: false`                                                                                                                                      |
| `ref` $bindable         | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                    |
| `children`                           | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                                                                                                       |
| `child`                              | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                             | | Data Attribute                                     | Value         | Description                                                                                      |
| ------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-command-group` | `''` | Present on the group element. |

### Command.GroupHeading

A heading element to provide an accessible label for a group of items.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                             | Value         | Description                                                                                              |
| --------------------------------------------------------------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-command-group-heading` | `''` | Present on the group heading element. |

### Command.GroupItems

The container for the items within a group.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                           | Value         | Description                                                                                            |
| ------------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-command-group-items` | `''` | Present on the group items element. |

### Command.Item

Represents a single item within the command menu. If you wish to render an anchor element to link to a page, use the `Command.LinkItem` component.

| Property                                                                                     | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` required | `string`                                                                                                                                                                                             | The value of the item.`Default:  undefined`                                                                                                                                    |
| `keywords`                                                 | `string[]`                                                                                                                                                                                           | An array of additional keywords or aliases that will be used to filter the item.`Default:  undefined`                                                                          |
| `forceMount`                                               | `boolean`                                                                                                                                                                                            | Whether or not the item should always be mounted to the DOM, regardless of the internal filtering logic`Default: false`                                                           |
| `onSelect`                                                 | `function`- () => void                                               | A callback that is fired when the item is selected.`Default:  undefined`                                                                                                       |
| `disabled`                                                 | `boolean`                                                                                                                                                                                            | Whether or not the combobox item is disabled. This will prevent interaction/selection.`Default: false`                                                                            |
| `ref` $bindable                               | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                 | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                    | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                     |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present when the item is disabled.                                       |
| `data-selected`                                      | `''` | Present when the item is selected.                                       |
| `data-command-item`                                  | `''` | Present on the item element. |

### Command.LinkItem

Similar to the `Command.Item` component, but renders an anchor element to take advantage of preloading before navigation.

| Property                                                                                     | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` required | `string`                                                                                                                                                                                             | The value of the item.`Default:  undefined`                                                                                                                                    |
| `keywords`                                                 | `string[]`                                                                                                                                                                                           | An array of additional keywords or aliases that will be used to filter the item.`Default:  undefined`                                                                          |
| `forceMount`                                               | `boolean`                                                                                                                                                                                            | Whether or not the item should always be mounted to the DOM, regardless of the internal filtering logic`Default: false`                                                           |
| `onSelect`                                                 | `function`- () => void                                               | A callback that is fired when the item is selected.`Default:  undefined`                                                                                                       |
| `disabled`                                                 | `boolean`                                                                                                                                                                                            | Whether or not the combobox item is disabled. This will prevent interaction/selection.`Default: false`                                                                            |
| `ref` $bindable                               | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                 | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                    | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                     |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present when the item is disabled.                                       |
| `data-selected`                                      | `''` | Present when the item is selected.                                       |
| `data-command-item`                                  | `''` | Present on the item element. |

### Command.Empty

A component to display when no results are found.

| Property                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `forceMount` | `boolean`                                                                                                                                                                                            | Whether or not to forcefully mount the empty state, regardless of the internal filtering logic. Useful when you want to handle filtering yourself.`Default: false`                |
| `ref` $bindable              | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                     | Value         | Description                                                                                      |
| ------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-command-empty` | `''` | Present on the empty element. |

### Command.Loading

A component to display while results are being fetched or processed.

| Property                                                                  | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `progress` | `number`                                                                                                                                                                                             | The progress of the loading state.`Default: 0`                                                                                                                                    |
| `ref` $bindable            | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                              | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                 | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                       | Value         | Description                                                                                        |
| --------------------------------------------------------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-command-loading` | `''` | Present on the loading element. |

### Command.Separator

A visual separator to divide different sections of the command list. Visible when the search query is empty or the `forceMount` prop is `true`.

| Property                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `forceMount` | `boolean`                                                                                                                                                                                            | Whether or not the separator should always be mounted to the DOM, regardless of the internal filtering logic`Default: false`                                                      |
| `ref` $bindable              | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                         | Value         | Description                                                                                          |
| ----------------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-command-separator` | `''` | Present on the separator element. |

----------------------------------------------------

# Context Menu Documentation

Displays options or actions relevant to a specific context or selected item, triggered by a right-click.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { ContextMenu } from "bits-ui";
  import CopySimple from "phosphor-svelte/lib/CopySimple";
  import MouseSimple from "phosphor-svelte/lib/MouseSimple";
  import PencilSimpleLine from "phosphor-svelte/lib/PencilSimpleLine";
  import PlusCircle from "phosphor-svelte/lib/PlusCircle";
  import Trash from "phosphor-svelte/lib/Trash";
</script>
<ContextMenu.Root>
  <ContextMenu.Trigger
    class="rounded-card border-border-input text-muted-foreground flex h-[188px] w-[279px] select-none items-center justify-center border-2 border-dashed bg-transparent font-semibold"
  >
    <div class="flex flex-col items-center justify-center gap-4 text-center">
      <MouseSimple class="size-8" />
      Right click me
    </div>
  </ContextMenu.Trigger>
  <ContextMenu.Portal>
    <ContextMenu.Content
      class="focus-override border-muted bg-background shadow-popover outline-hidden focus-visible:outline-hidden w-[229px] rounded-xl border px-1 py-1.5"
    >
      <ContextMenu.Item
        class="rounded-button data-highlighted:bg-muted outline-hidden ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
      >
        <div class="flex items-center">
          <PencilSimpleLine class="text-foreground-alt mr-2 size-5" />
          Edit
        </div>
        <div class="ml-auto flex items-center gap-px">
          <kbd
            class="rounded-button border-dark-10 bg-background-alt text-muted-foreground shadow-kbd inline-flex size-5 items-center justify-center border text-[13px]"
          >
            
          </kbd>
          <kbd
            class="rounded-button border-dark-10 bg-background-alt text-muted-foreground shadow-kbd inline-flex size-5 items-center justify-center border text-[11px]"
          >
            E
          </kbd>
        </div>
      </ContextMenu.Item>
      <ContextMenu.Sub>
        <ContextMenu.SubTrigger
          class="rounded-button data-highlighted:bg-muted data-[state=open]:bg-muted outline-hidden ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
        >
          <div class="flex items-center">
            <PlusCircle class="text-foreground-alt mr-2 size-5" />
            Add
          </div>
          <div class="ml-auto flex items-center gap-px">
            <kbd
              class="rounded-button border-dark-10 bg-background-alt text-muted-foreground shadow-kbd inline-flex size-5 items-center justify-center border text-[13px]"
            >
              
            </kbd>
            <kbd
              class="rounded-button border-dark-10 bg-background-alt text-muted-foreground shadow-kbd inline-flex size-5 items-center justify-center border text-[11px]"
            >
              N
            </kbd>
          </div>
        </ContextMenu.SubTrigger>
        <ContextMenu.SubContent
          class="border-muted bg-background shadow-popover z-100 ring-0! ring-transparent! w-[209px] rounded-xl border px-1 py-1.5"
          sideOffset={10}
        >
          <ContextMenu.Item
            class="rounded-button data-highlighted:bg-muted outline-hidden ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-normal"
          >
            Header
          </ContextMenu.Item>
          <ContextMenu.Item
            class="rounded-button data-highlighted:bg-muted outline-hidden ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-normal"
          >
            Paragraph
          </ContextMenu.Item>
          <ContextMenu.Item
            class="rounded-button data-highlighted:bg-muted outline-hidden ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-normal"
          >
            Codeblock
          </ContextMenu.Item>
          <ContextMenu.Item
            class="rounded-button data-highlighted:bg-muted outline-hidden ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-normal"
          >
            List
          </ContextMenu.Item>
          <ContextMenu.Item
            class="rounded-button data-highlighted:bg-muted outline-hidden ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-normal"
          >
            Task
          </ContextMenu.Item>
        </ContextMenu.SubContent>
      </ContextMenu.Sub>
      <ContextMenu.Item
        class="rounded-button data-highlighted:bg-muted outline-hidden ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
      >
        <div class="flex items-center">
          <CopySimple class="text-foreground-alt mr-2 size-5" />
          Duplicate
        </div>
        <div class="ml-auto flex items-center gap-px">
          <kbd
            class="rounded-button border-dark-10 bg-background-alt text-muted-foreground shadow-kbd inline-flex size-5 items-center justify-center border text-[13px]"
          >
            
          </kbd>
          <kbd
            class="rounded-button border-dark-10 bg-background-alt text-muted-foreground shadow-kbd inline-flex size-5 items-center justify-center border text-[11px]"
          >
            D
          </kbd>
        </div>
      </ContextMenu.Item>
      <ContextMenu.Separator class="bg-muted -mx-1 my-1 block h-px" />
      <ContextMenu.Item
        class="rounded-button data-highlighted:bg-muted outline-hidden ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
      >
        <div class="flex items-center">
          <Trash class="text-foreground-alt mr-2 size-5" />
          Delete
        </div>
      </ContextMenu.Item>
    </ContextMenu.Content>
  </ContextMenu.Portal>
</ContextMenu.Root>
```

## Structure

```svelte
<script lang="ts">
 import { ContextMenu } from "bits-ui";
</script>
<ContextMenu.Root>
 <ContextMenu.Trigger />
 <ContextMenu.Portal>
  <ContextMenu.Content>
   <ContextMenu.Group>
    <ContextMenu.GroupHeading />
    <ContextMenu.Item />
   </ContextMenu.Group>
   <ContextMenu.Item />
   <ContextMenu.CheckboxItem>
    {#snippet children({ checked })}
     {checked ? "" : ""}
    {/snippet}
   </ContextMenu.CheckboxItem>
   <ContextMenu.RadioGroup>
    <ContextMenu.GroupHeading />
    <ContextMenu.RadioItem>
     {#snippet children({ checked })}
      {checked ? "" : ""}
     {/snippet}
    </ContextMenu.RadioItem>
   </ContextMenu.RadioGroup>
   <ContextMenu.Sub>
    <ContextMenu.SubTrigger />
    <ContextMenu.SubContent />
   </ContextMenu.Sub>
   <ContextMenu.Separator />
   <ContextMenu.Arrow />
  </ContextMenu.Content>
 </ContextMenu.Portal>
</ContextMenu.Root>
```

## Reusable Components

If you're planning to use Context Menu in multiple places, you can create a reusable component that wraps the Context Menu component.

This example shows you how to create a Context Menu component that accepts a few custom props that make it more capable.

CustomContextMenu.svelte

```svelte
<script lang="ts">
 import type { Snippet } from "svelte";
 import { ContextMenu, type WithoutChild } from "bits-ui";
 type Props = ContextMenu.Props & {
  trigger: Snippet;
  items: string[];
  contentProps?: WithoutChild<ContextMenu.Content.Props>;
  // other component props if needed
 };
 let {
  open = $bindable(false),
  children,
  trigger,
  items,
  contentProps,
  ...restProps
 }: Props = $props();
</script>
<ContextMenu.Root bind:open {...restProps}>
 <ContextMenu.Trigger>
  {@render trigger()}
 </ContextMenu.Trigger>
 <ContextMenu.Portal>
  <ContextMenu.Content {...contentProps}>
   <ContextMenu.Group>
    <ContextMenu.GroupHeading>Select an Office</ContextMenu.GroupHeading>
    {#each items as item}
     <ContextMenu.Item textValue={item}>
      {item}
     </ContextMenu.Item>
    {/each}
   </ContextMenu.Group>
  </ContextMenu.Content>
 </ContextMenu.Portal>
</ContextMenu.Root>
```

You can then use the `CustomContextMenu` component like this:

```svelte
<script lang="ts">
 import CustomContextMenu from "./CustomContextMenu.svelte";
</script>
<CustomContextMenu items={["Dunder Mifflin", "Vance Refrigeration", "Michael Scott Paper Company"]}>
 {#snippet triggerArea()}
  <div class="grid size-20 place-items-center rounded-lg border border-dashed p-4">
   Right-click me
  </div>
 {/snippet}
</CustomContextMenu>
```

Alternatively, you can define the snippet(s) separately and pass them as props to the component:

```svelte
<script lang="ts">
 import CustomContextMenu from "./CustomContextMenu.svelte";
</script>
{#snippet triggerArea()}
 <div class="grid size-20 place-items-center rounded-lg border border-dashed p-4">
  Right-click me
 </div>
{/snippet}
<CustomContextMenu
 items={["Dunder Mifflin", "Vance Refrigeration", "Michael Scott Paper Company"]}
 {triggerArea}
/>
```

## Managing Open State

This section covers how to manage the `open` state of the menu.

### Two-Way Binding

Use `bind:open` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { ContextMenu } from "bits-ui";
 let isOpen = $state(false);
</script>
<button onclick={() => (isOpen = true)}>Open Context Menu</button>
<ContextMenu.Root bind:open={isOpen}>
</ContextMenu.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { ContextMenu } from "bits-ui";
 let myOpen = $state(false);
 function getOpen() {
  return myOpen;
 }
 function setOpen(newOpen: boolean) {
  myOpen = newopen;
 }
</script>
<ContextMenu.Root bind:open={getOpen, setOpen}>
</ContextMenu.Root>
```

## Checkbox Items

You can use the `ContextMenu.CheckboxItem` component to create a `menuitemcheckbox` element to add checkbox functionality to menu items.

```svelte
<script lang="ts">
 import { ContextMenu } from "bits-ui";
 let notifications = $state(true);
</script>
<ContextMenu.CheckboxItem bind:checked={notifications}>
 {#snippet children({ checked, indeterminate })}
  {#if indeterminate}
   -
  {:else if checked}
   
  {/if}
  Notifications
 {/snippet}
</ContextMenu.CheckboxItem>
```

See the [CheckboxItem API](#checkboxitem) for more information.

## Radio Groups

You can combine the `ContextMenu.RadioGroup` and `ContextMenu.RadioItem` components to create a radio group within a menu.

```svelte
<script lang="ts">
 import { ContextMenu } from "bits-ui";
 const values = ["one", "two", "three"];
 let value = $state("one");
</script>
<ContextMenu.RadioGroup bind:value>
 {#each values as value}
  <ContextMenu.RadioItem {value}>
   {#snippet children({ checked })}
    {#if checked}
     
    {/if}
    {value}
   {/snippet}
  </ContextMenu.RadioItem>
 {/each}
</ContextMenu.RadioGroup>
```

See the [RadioGroup](#radiogroup) and [RadioItem](#radioitem) APIs for more information.

## Nested Menus

You can create nested menus using the `ContextMenu.Sub` component to create complex menu structures.

```svelte
<script lang="ts">
 import { ContextMenu } from "bits-ui";
</script>
<ContextMenu.Content>
 <ContextMenu.Item>Item 1</ContextMenu.Item>
 <ContextMenu.Item>Item 2</ContextMenu.Item>
 <ContextMenu.Sub>
  <ContextMenu.SubTrigger>Open Sub Menu</ContextMenu.SubTrigger>
  <ContextMenu.SubContent>
   <ContextMenu.Item>Sub Item 1</ContextMenu.Item>
   <ContextMenu.Item>Sub Item 2</ContextMenu.Item>
  </ContextMenu.SubContent>
 </ContextMenu.Sub>
</ContextMenu.Content>
```

## Svelte Transitions

You can use the `forceMount` prop along with the `child` snippet to forcefully mount the `ContextMenu.Content` component to use Svelte Transitions or another animation library that requires more control.

```svelte
<script lang="ts">
 import { ContextMenu } from "bits-ui";
 import { fly } from "svelte/transition";
</script>
<ContextMenu.Content forceMount>
 {#snippet child({ wrapperProps, props, open })}
  {#if open}
   <div {...wrapperProps}>
    <div {...props} transition:fly>
     <ContextMenu.Item>Item 1</ContextMenu.Item>
     <ContextMenu.Item>Item 2</ContextMenu.Item>
    </div>
   </div>
  {/if}
 {/snippet}
</ContextMenu.Content>
```

Of course, this isn't the prettiest syntax, so it's recommended to create your own reusable content component that handles this logic if you intend to use this approach. For more information on using transitions with Bits UI components, see the [Transitions](/docs/transitions) documentation.

```svelte
<script lang="ts">
  import { ContextMenu } from "bits-ui";
  import CopySimple from "phosphor-svelte/lib/CopySimple";
  import MouseSimple from "phosphor-svelte/lib/MouseSimple";
  import PencilSimpleLine from "phosphor-svelte/lib/PencilSimpleLine";
  import PlusCircle from "phosphor-svelte/lib/PlusCircle";
  import Trash from "phosphor-svelte/lib/Trash";
  import { fly } from "svelte/transition";
</script>
<ContextMenu.Root>
  <ContextMenu.Trigger
    class="rounded-card border-border-input text-muted-foreground flex h-[188px] w-[279px] select-none items-center justify-center border-2 border-dashed bg-transparent font-semibold"
  >
    <div class="flex flex-col items-center justify-center gap-4 text-center">
      <MouseSimple class="size-8" />
      Right click me
    </div>
  </ContextMenu.Trigger>
  <ContextMenu.Portal>
    <ContextMenu.Content
      class="focus-override border-muted bg-background shadow-popover outline-hidden focus-visible:outline-hidden w-[229px] rounded-xl border px-1 py-1.5"
      forceMount
    >
      {#snippet child({ wrapperProps, props, open })}
        {#if open}
          <div {...wrapperProps}>
            <div {...props} transition:fly={{ duration: 300 }}>
              <ContextMenu.Item
                class="rounded-button data-highlighted:bg-muted outline-hidden ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
              >
                <div class="flex items-center">
                  <PencilSimpleLine class="text-foreground-alt mr-2 size-5" />
                  Edit
                </div>
                <div class="ml-auto flex items-center gap-px">
                  <kbd
                    class="rounded-button border-dark-10 bg-background-alt text-muted-foreground shadow-kbd inline-flex size-5 items-center justify-center border text-[13px]"
                  >
                    
                  </kbd>
                  <kbd
                    class="rounded-button border-dark-10 bg-background-alt text-muted-foreground shadow-kbd inline-flex size-5 items-center justify-center border text-[11px]"
                  >
                    E
                  </kbd>
                </div>
              </ContextMenu.Item>
              <ContextMenu.Sub>
                <ContextMenu.SubTrigger
                  class="rounded-button data-highlighted:bg-muted data-[state=open]:bg-muted outline-hidden ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
                >
                  <div class="flex items-center">
                    <PlusCircle class="text-foreground-alt mr-2 size-5" />
                    Add
                  </div>
                  <div class="ml-auto flex items-center gap-px">
                    <kbd
                      class="rounded-button border-dark-10 bg-background-alt text-muted-foreground shadow-kbd inline-flex size-5 items-center justify-center border text-[13px]"
                    >
                      
                    </kbd>
                    <kbd
                      class="rounded-button border-dark-10 bg-background-alt text-muted-foreground shadow-kbd inline-flex size-5 items-center justify-center border text-[11px]"
                    >
                      N
                    </kbd>
                  </div>
                </ContextMenu.SubTrigger>
                <ContextMenu.SubContent
                  class="border-muted bg-background shadow-popover z-100 ring-0! ring-transparent! w-[209px] rounded-xl border px-1 py-1.5"
                  sideOffset={10}
                >
                  <ContextMenu.Item
                    class="rounded-button data-highlighted:bg-muted outline-hidden ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-normal"
                  >
                    Header
                  </ContextMenu.Item>
                  <ContextMenu.Item
                    class="rounded-button data-highlighted:bg-muted outline-hidden ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-normal"
                  >
                    Paragraph
                  </ContextMenu.Item>
                  <ContextMenu.Item
                    class="rounded-button data-highlighted:bg-muted outline-hidden ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-normal"
                  >
                    Codeblock
                  </ContextMenu.Item>
                  <ContextMenu.Item
                    class="rounded-button data-highlighted:bg-muted outline-hidden ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-normal"
                  >
                    List
                  </ContextMenu.Item>
                  <ContextMenu.Item
                    class="rounded-button data-highlighted:bg-muted outline-hidden ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-normal"
                  >
                    Task
                  </ContextMenu.Item>
                </ContextMenu.SubContent>
              </ContextMenu.Sub>
              <ContextMenu.Item
                class="rounded-button data-highlighted:bg-muted outline-hidden ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
              >
                <div class="flex items-center">
                  <CopySimple class="text-foreground-alt mr-2 size-5" />
                  Duplicate
                </div>
                <div class="ml-auto flex items-center gap-px">
                  <kbd
                    class="rounded-button border-dark-10 bg-background-alt text-muted-foreground shadow-kbd inline-flex size-5 items-center justify-center border text-[13px]"
                  >
                    
                  </kbd>
                  <kbd
                    class="rounded-button border-dark-10 bg-background-alt text-muted-foreground shadow-kbd inline-flex size-5 items-center justify-center border text-[11px]"
                  >
                    D
                  </kbd>
                </div>
              </ContextMenu.Item>
              <ContextMenu.Separator class="bg-muted -mx-1 my-1 block h-px" />
              <ContextMenu.Item
                class="rounded-button data-highlighted:bg-muted outline-hidden ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
              >
                <div class="flex items-center">
                  <Trash class="text-foreground-alt mr-2 size-5" />
                  Delete
                </div>
              </ContextMenu.Item>
            </div>
          </div>
        {/if}
      {/snippet}
    </ContextMenu.Content>
  </ContextMenu.Portal>
</ContextMenu.Root>
```

## API Reference

### ContextMenu.Root

The root component which manages & scopes the state of the context menu.

| Property                                                                                     | Type                                                                                                                                                                                                           | Description                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `open` $bindable | `boolean`                                                                                                                                                           | The open state of the menu.`Default: false`                                                 |
| `onOpenChange`                                             | `function`- (open: boolean) => void | A callback that is fired when the menu's open state changes.`Default:  undefined`        |
| `dir`                                                      | `enum`- 'ltr' \| 'rtl'              | The reading direction of the app.`Default: 'ltr'`                                           |
| `children`                                                 | `Snippet`                                                                                                                                                           | The children content to render.`Default:  undefined` |

### ContextMenu.Trigger

The element which when right-clicked, opens the context menu.

| Property                                                                  | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `disabled` | `boolean`                                                                                                                                                                                            | Whether or not the menu trigger is disabled.`Default: false`                                                                                                                      |
| `ref` $bindable            | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                              | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                 | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                        |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | The open state of the menu or submenu the element controls or belongs to.   |
| `data-menu-trigger`                               | `''`                                                                                                                                                                                 | Present on the trigger element. |

### ContextMenu.Portal

A component that portals the content of the dropdown menu to the body or a custom target (if provided).

| Property                                                            | Type                                                                                                                                                                                                                           | Description                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `to` | `union`- string \| HTMLElement \| null \| undefined | Where to render the content when it is open. Defaults to the body. Can be disabled by passing `null``Default: body`              |
| `disabled`                        | `boolean`                                                                                                                                                                           | Whether the portal is disabled or not. When disabled, the content will be rendered in its original DOM location.`Default: false` |
| `children`                        | `Snippet`                                                                                                                                                                           | The children content to render.`Default:  undefined`                                      |

### ContextMenu.Content

The content displayed when the context menu is open.

| Property                                                                     | Type                                                                                                                                                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `alignOffset` | `number`                                                                                                                                                                                                           | The distance in pixels from the anchor to the floating element.`Default: 0`                                                                                                                                                                                                                                                                                                                                                        |
| `arrowPadding`                             | `number`                                                                                                                                                                                                           | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0`                                                                                                                                                                                                                                                                                                  |
| `avoidCollisions`                          | `boolean`                                                                                                                                                                                                          | When `true`, overrides the `side` and `align` options to prevent collisions with the boundary edges.`Default: true`                                                                                                                                                                                                                                                                                                                |
| `collisionBoundary`                        | `union`- Element \| null                                                           | A boundary element or array of elements to check for collisions against.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                   |
| `collisionPadding`                         | `union`- number \| Partial\&lt;Record\&lt;Side, number\&gt;\&gt;                   | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0`                                                                                                                                                                                                                                                                                                  |
| `sticky`                                   | `enum`- 'partial' \| 'always'                                                      | The sticky behavior on the align axis. `'partial'` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst `'always'` will keep the content in the boundary regardless.`Default: partial`                                                                                                                                                                                        |
| `hideWhenDetached`                         | `boolean`                                                                                                                                                                                                          | When `true`, hides the content when it is detached from the DOM. This is useful for when you want to hide the content when the user scrolls away.`Default: true`                                                                                                                                                                                                                                                                   |
| `updatePositionStrategy`                   | `enum`- 'optimized' \| 'always'                                                    | The strategy to use when updating the position of the content. When `'optimized'` the content will only be repositioned when the trigger is in the viewport. When `'always'` the content will be repositioned whenever the position changes.`Default: optimized`                                                                                                                                                                   |
| `strategy`                                 | `enum`- 'fixed' \| 'absolute'                                                      | The positioning strategy to use for the floating element. When `'fixed'` the element will be positioned relative to the viewport. When `'absolute'` the element will be positioned relative to the nearest positioned ancestor.`Default: fixed`                                                                                                                                                                                    |
| `preventScroll`                            | `boolean`                                                                                                                                                                                                          | When `true`, prevents the body from scrolling when the content is open. This is useful when you want to use the content as a modal.`Default: true`                                                                                                                                                                                                                                                                                 |
| `customAnchor`                             | `union`- string \| HTMLElement \| Measurable \| null                               | Use an element other than the trigger to anchor the content to. If provided, the content will be anchored to the provided element instead of the trigger.`Default: null`                                                                                                                                                                                                                                                           |
| `onEscapeKeydown`                          | `function`- (event: KeyboardEvent) => void                                         | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default:  undefined`                                                                                                                                                                                                                    |
| `escapeKeydownBehavior`                    | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` |
| `onInteractOutside`                        | `function`- (event: PointerEvent) => void                                          | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default:  undefined`                                                                                                                                                                                                        |
| `onFocusOutside`                           | `function`- (event: FocusEvent) => void                                            | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default:  undefined`                                                                                                                                                                                                                                                  |
| `interactOutsideBehavior`                  | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close`  |
| `onOpenAutoFocus`                          | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is opened. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `onCloseAutoFocus`                         | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is closed. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `trapFocus`                                | `boolean`                                                                                                                                                                                                          | Whether or not to trap the focus within the content when open.`Default: true`                                                                                                                                                                                                                                                                                                                                                      |
| `preventOverflowTextSelection`             | `boolean`                                                                                                                                                                                                          | When `true`, prevents the text selection from overflowing the bounds of the element.`Default: true`                                                                                                                                                                                                                                                                                                                                |
| `dir`                                      | `enum`- 'ltr' \| 'rtl'                                                             | The reading direction of the app.`Default: 'ltr'`                                                                                                                                                                                                                                                                                                                                                                                  |
| `forceMount`                               | `boolean`                                                                                                                                                                                                          | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                                                                                                                                                                                                                                                                 |
| `loop`                                     | `boolean`                                                                                                                                                                                                          | Whether or not the context menu should loop through items when reaching the end.`Default: false`                                                                                                                                                                                                                                                                                                                                   |
| `ref` $bindable               | `HTMLDivElement`                                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                                                                                                                                                                         |
| `children`                                 | `Snippet`                                                                                                                                                                                                          | The children content to render.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                                                            |
| `child`                                    | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };               | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                                                                                                                                                                  | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                        |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | The open state of the menu or submenu the element controls or belongs to.   |
| `data-menu-content`                               | `''`                                                                                                                                                                                 | Present on the content element. |

| CSS Variable                                                                 | Description                                                                                                        |
| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--bits-context-menu-content-transform-origin` | The transform origin of the context menu content element.                                   |
| `--bits-context-menu-content-available-width`                                       | The available width of the context menu content element.                                    |
| `--bits-context-menu-content-available-height`                                      | The available height of the context menu content element.                                   |
| `--bits-context-menu-anchor-width`                                                  | The width of the context menu trigger element.                                              |
| `--bits-context-menu-anchor-height`                                                 | The height of the context menu trigger element. |

### ContextMenu.ContentStatic

The content displayed when the context menu is open. (Static/No Floating UI)

| Property                                                                         | Type                                                                                                                                                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onEscapeKeydown` | `function`- (event: KeyboardEvent) => void                                         | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default:  undefined`                                                                                                                                                                                                                    |
| `escapeKeydownBehavior`                        | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` |
| `onInteractOutside`                            | `function`- (event: PointerEvent) => void                                          | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default:  undefined`                                                                                                                                                                                                        |
| `onFocusOutside`                               | `function`- (event: FocusEvent) => void                                            | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default:  undefined`                                                                                                                                                                                                                                                  |
| `interactOutsideBehavior`                      | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close`  |
| `onOpenAutoFocus`                              | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is opened. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `onCloseAutoFocus`                             | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is closed. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `trapFocus`                                    | `boolean`                                                                                                                                                                                                          | Whether or not to trap the focus within the content when open.`Default: true`                                                                                                                                                                                                                                                                                                                                                      |
| `preventScroll`                                | `boolean`                                                                                                                                                                                                          | When `true`, prevents the body from scrolling when the content is open. This is useful when you want to use the content as a modal.`Default: true`                                                                                                                                                                                                                                                                                 |
| `preventOverflowTextSelection`                 | `boolean`                                                                                                                                                                                                          | When `true`, prevents the text selection from overflowing the bounds of the element.`Default: true`                                                                                                                                                                                                                                                                                                                                |
| `dir`                                          | `enum`- 'ltr' \| 'rtl'                                                             | The reading direction of the app.`Default: 'ltr'`                                                                                                                                                                                                                                                                                                                                                                                  |
| `forceMount`                                   | `boolean`                                                                                                                                                                                                          | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                                                                                                                                                                                                                                                                 |
| `loop`                                         | `boolean`                                                                                                                                                                                                          | Whether or not the context menu should loop through items when reaching the end.`Default: false`                                                                                                                                                                                                                                                                                                                                   |
| `ref` $bindable                   | `HTMLDivElement`                                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                                                                                                                                                                         |
| `children`                                     | `Snippet`                                                                                                                                                                                                          | The children content to render.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                                                            |
| `child`                                        | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };               | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                                                                                                                                                                  | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                        |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | The open state of the menu or submenu the element controls or belongs to.   |
| `data-menu-content`                               | `''`                                                                                                                                                                                 | Present on the content element. |

### ContextMenu.Item

A menu item within the context menu.

| Property                                                                  | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `disabled` | `boolean`                                                                                                                                                                                            | Whether or not the menu item is disabled.`Default: false`                                                                                                                         |
| `textValue`                             | `string`                                                                                                                                                                                             | The text value of the checkbox menu item. This is used for typeahead.`Default:  undefined`                                                                                     |
| `onSelect`                              | `function`- () => void                                               | A callback that is fired when the menu item is selected.`Default:  undefined`                                                                                                  |
| `closeOnSelect`                         | `boolean`                                                                                                                                                                                            | Whether or not the menu item should close when selected.`Default: true`                                                                                                           |
| `ref` $bindable            | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                              | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                 | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                   | Value                 | Description                                                                                     |
| ----------------------------------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-orientation` | `'vertical'` |                                                                                       |
| `data-highlighted`                                      | `''`         | Present when the menu item is highlighted.                               |
| `data-disabled`                                         | `''`         | Present when the menu item is disabled.                                  |
| `data-menu-item`                                        | `''`         | Present on the item element. |

### ContextMenu.CheckboxItem

A menu item that can be controlled and toggled like a checkbox.

| Property                                                                  | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `disabled` | `boolean`                                                                                                                                                                                            | Whether or not the checkbox menu item is disabled. Disabled items cannot be interacted with and are skipped when navigating with the keyboard.`Default: false`                    |
| `checked` $bindable        | `boolean`                                                                                                                                                                                            | The checkbox menu item's checked state.`Default: false`                                                                                                                           |
| `onCheckedChange`                       | `function`- (checked: boolean) => void                               | A callback that is fired when the checkbox menu item's checked state changes.`Default:  undefined`                                                                             |
| `indeterminate` $bindable  | `boolean`                                                                                                                                                                                            | Whether the checkbox menu item is in an indeterminate state or not.`Default: false`                                                                                               |
| `onIndeterminateChange`                 | `function`- (indeterminate: boolean) => void                         | A callback that is fired when the indeterminate state changes.`Default:  undefined`                                                                                            |
| `textValue`                             | `string`                                                                                                                                                                                             | The text value of the checkbox menu item. This is used for typeahead.`Default:  undefined`                                                                                     |
| `onSelect`                              | `function`- () => void                                               | A callback that is fired when the menu item is selected.`Default:  undefined`                                                                                                  |
| `closeOnSelect`                         | `boolean`                                                                                                                                                                                            | Whether or not the menu item should close when selected.`Default: true`                                                                                                           |
| `ref` $bindable            | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                              | `Snippet`- Snippet                                                   | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                 | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                   | Value                                                                                                                                                                         | Description                                                                                                |
| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-orientation` | `'vertical'`                                                                                                                                                         |                                                                                                  |
| `data-highlighted`                                      | `''`                                                                                                                                                                 | Present when the menu item is highlighted.                                          |
| `data-disabled`                                         | `''`                                                                                                                                                                 | Present when the menu item is disabled.                                             |
| `data-state`                                            | `enum`- '' | The checkbox menu item's checked state. | ### ContextMenu.RadioGroup

A group of radio menu items, where only one can be checked at a time.

| Property                                                                                      | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` $bindable | `string`                                                                                                                                                                                             | The value of the currently checked radio menu item.`Default:  undefined`                                                                                                       |
| `onValueChange`                                             | `function`- (value: string) => void                                  | A callback that is fired when the radio group's value changes.`Default:  undefined`                                                                                            |
| `ref` $bindable                                | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                  | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                     | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                        | Value         | Description                                                                                            |
| ---------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-menu-radio-group` | `''` | Present on the radio group element. |

### ContextMenu.RadioItem

A menu item that can be controlled and toggled like a radio button. It must be a child of a `RadioGroup`.

| Property                                                                                     | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` required | `string`                                                                                                                                                                                             | The value of the radio item. When checked, the parent `RadioGroup`'s value will be set to this value.`Default:  undefined`                                                     |
| `disabled`                                                 | `boolean`                                                                                                                                                                                            | Whether or not the radio menu item is disabled. Disabled items cannot be interacted with and are skipped when navigating with the keyboard.`Default: false`                       |
| `textValue`                                                | `string`                                                                                                                                                                                             | The text value of the checkbox menu item. This is used for typeahead.`Default:  undefined`                                                                                     |
| `onSelect`                                                 | `function`- () => void                                               | A callback that is fired when the menu item is selected.`Default:  undefined`                                                                                                  |
| `closeOnSelect`                                            | `boolean`                                                                                                                                                                                            | Whether or not the menu item should close when selected.`Default: true`                                                                                                           |
| `ref` $bindable                               | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                 | `Snippet`- Snippet                                                   | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                    | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                   | Value                                                                                                                                                                         | Description                                                                                           |
| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-orientation` | `'vertical'`                                                                                                                                                         |                                                                                             |
| `data-highlighted`                                      | `''`                                                                                                                                                                 | Present when the menu item is highlighted.                                     |
| `data-disabled`                                         | `''`                                                                                                                                                                 | Present when the menu item is disabled.                                        |
| `data-state`                                            | `enum`- '' | The radio menu item's checked state.                                           |
| `data-value`                                            | `''`                                                                                                                                                                 | The value of the radio item.                                                   |
| `data-menu-radio-item`                                  | `''`                                                                                                                                                                 | Present on the radio item element. |

### ContextMenu.Separator

A horizontal line to visually separate menu items.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                   | Value                 | Description                                                                                          |
| ----------------------------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-orientation` | `'vertical'` | The orientation of the separator.                                             |
| `data-menu-separator`                                   | `''`         | Present on the separator element. |

### ContextMenu.Arrow

An optional arrow which points to the context menu's anchor/trigger point.

| Property                                                               | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `width` | `number`                                                                                                                                                                                             | The width of the arrow in pixels.`Default: 8`                                                                                                                                     |
| `height`                             | `number`                                                                                                                                                                                             | The height of the arrow in pixels.`Default: 8`                                                                                                                                    |
| `ref` $bindable         | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                           | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                              | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                      |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-state` | `enum`- 'open' \| 'closed' | The open state of the menu or submenu the element controls or belongs to. |
| `data-menu-arrow`                                 | `''`                                                                                                                                                                                 | Present on the arrow element. |

### ContextMenu.Group

A group of menu items. It should be passed an `aria-label` or have a child `Menu.GroupHeading` component to provide a label for a group of menu items.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                  | Value         | Description                                                                                      |
| ---------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-menu-group` | `''` | Present on the group element. |

### ContextMenu.GroupHeading

A heading for a group which will be skipped when navigating with the keyboard. It is used to provide a visual label for a group of menu items and must be a child of either a `ContextMenu.Group` or `ContextMenu.RadioGroup` component.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                          | Value         | Description                                                                                              |
| ------------------------------------------------------------------------------------------ | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-menu-group-heading` | `''` | Present on the group heading element. |

### ContextMenu.Sub

A submenu belonging to the parent context menu. Responsible for managing the state of the submenu.

| Property                                                                                     | Type                                                                                                                                                                                                           | Description                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `open` $bindable | `boolean`                                                                                                                                                           | The open state of the submenu.`Default: false`                                              |
| `onOpenChange`                                             | `function`- (open: boolean) => void | A callback that is fired when the submenu's open state changes.`Default:  undefined`     |
| `children`                                                 | `Snippet`                                                                                                                                                           | The children content to render.`Default:  undefined` |

### ContextMenu.SubTrigger

A menu item which when pressed or hovered, opens the submenu it is a child of.

| Property                                                                  | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `disabled` | `boolean`                                                                                                                                                                                            | Whether or not the submenu trigger is disabled.`Default: false`                                                                                                                   |
| `textValue`                             | `string`                                                                                                                                                                                             | The text value of the checkbox menu item. This is used for typeahead.`Default:  undefined`                                                                                     |
| `onSelect`                              | `function`- () => void                                               | A callback that is fired when the menu item is selected.`Default:  undefined`                                                                                                  |
| `closeOnSelect`                         | `boolean`                                                                                                                                                                                            | Whether or not the menu item should close when selected.`Default: true`                                                                                                           |
| `ref` $bindable            | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                              | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                 | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                   | Value                                                                                                                                                                                         | Description                                                                                                |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-orientation` | `'vertical'`                                                                                                                                                                         |                                                                                                  |
| `data-highlighted`                                      | `''`                                                                                                                                                                                 | Present when the menu item is highlighted.                                          |
| `data-disabled`                                         | `''`                                                                                                                                                                                 | Present when the menu item is disabled.                                             |
| `data-state`                                            | `enum`- 'open' \| 'closed' | The open state of the menu or submenu the element controls or belongs to.           |
| `data-menu-sub-trigger`                                 | `''`                                                                                                                                                                                 | Present on the submenu trigger element. |

### ContextMenu.SubContent

The submenu content displayed when the parent submenu is open.

| Property                                                              | Type                                                                                                                                                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `side` | `enum`- 'top' \| 'bottom' \| 'left' \| 'right'                                     | The preferred side of the anchor to render the floating element against when open. Will be reversed when collisions occur.`Default: bottom`                                                                                                                                                                                                                                                                                        |
| `sideOffset`                        | `number`                                                                                                                                                                                                           | The distance in pixels from the anchor to the floating element.`Default: 0`                                                                                                                                                                                                                                                                                                                                                        |
| `align`                             | `enum`- 'start' \| 'center' \| 'end'                                               | The preferred alignment of the anchor to render the floating element against when open. This may change when collisions occur.`Default: start`                                                                                                                                                                                                                                                                                     |
| `alignOffset`                       | `number`                                                                                                                                                                                                           | The distance in pixels from the anchor to the floating element.`Default: 0`                                                                                                                                                                                                                                                                                                                                                        |
| `arrowPadding`                      | `number`                                                                                                                                                                                                           | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0`                                                                                                                                                                                                                                                                                                  |
| `avoidCollisions`                   | `boolean`                                                                                                                                                                                                          | When `true`, overrides the `side` and `align` options to prevent collisions with the boundary edges.`Default: true`                                                                                                                                                                                                                                                                                                                |
| `collisionBoundary`                 | `union`- Element \| null                                                           | A boundary element or array of elements to check for collisions against.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                   |
| `collisionPadding`                  | `union`- number \| Partial\&lt;Record\&lt;Side, number\&gt;\&gt;                   | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0`                                                                                                                                                                                                                                                                                                  |
| `sticky`                            | `enum`- 'partial' \| 'always'                                                      | The sticky behavior on the align axis. `'partial'` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst `'always'` will keep the content in the boundary regardless.`Default: partial`                                                                                                                                                                                        |
| `hideWhenDetached`                  | `boolean`                                                                                                                                                                                                          | When `true`, hides the content when it is detached from the DOM. This is useful for when you want to hide the content when the user scrolls away.`Default: true`                                                                                                                                                                                                                                                                   |
| `updatePositionStrategy`            | `enum`- 'optimized' \| 'always'                                                    | The strategy to use when updating the position of the content. When `'optimized'` the content will only be repositioned when the trigger is in the viewport. When `'always'` the content will be repositioned whenever the position changes.`Default: optimized`                                                                                                                                                                   |
| `strategy`                          | `enum`- 'fixed' \| 'absolute'                                                      | The positioning strategy to use for the floating element. When `'fixed'` the element will be positioned relative to the viewport. When `'absolute'` the element will be positioned relative to the nearest positioned ancestor.`Default: fixed`                                                                                                                                                                                    |
| `preventScroll`                     | `boolean`                                                                                                                                                                                                          | When `true`, prevents the body from scrolling when the content is open. This is useful when you want to use the content as a modal.`Default: true`                                                                                                                                                                                                                                                                                 |
| `customAnchor`                      | `union`- string \| HTMLElement \| Measurable \| null                               | Use an element other than the trigger to anchor the content to. If provided, the content will be anchored to the provided element instead of the trigger.`Default: null`                                                                                                                                                                                                                                                           |
| `onEscapeKeydown`                   | `function`- (event: KeyboardEvent) => void                                         | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default:  undefined`                                                                                                                                                                                                                    |
| `escapeKeydownBehavior`             | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` |
| `onInteractOutside`                 | `function`- (event: PointerEvent) => void                                          | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default:  undefined`                                                                                                                                                                                                        |
| `onFocusOutside`                    | `function`- (event: FocusEvent) => void                                            | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default:  undefined`                                                                                                                                                                                                                                                  |
| `interactOutsideBehavior`           | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close`  |
| `onOpenAutoFocus`                   | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is opened. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `onCloseAutoFocus`                  | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is closed. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `trapFocus`                         | `boolean`                                                                                                                                                                                                          | Whether or not to trap the focus within the content when open.`Default: true`                                                                                                                                                                                                                                                                                                                                                      |
| `forceMount`                        | `boolean`                                                                                                                                                                                                          | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                                                                                                                                                                                                                                                                 |
| `preventOverflowTextSelection`      | `boolean`                                                                                                                                                                                                          | When `true`, prevents the text selection from overflowing the bounds of the element.`Default: true`                                                                                                                                                                                                                                                                                                                                |
| `dir`                               | `enum`- 'ltr' \| 'rtl'                                                             | The reading direction of the app.`Default: 'ltr'`                                                                                                                                                                                                                                                                                                                                                                                  |
| `loop`                              | `boolean`                                                                                                                                                                                                          | Whether or not to loop through the menu items in when navigating with the keyboard.`Default: false`                                                                                                                                                                                                                                                                                                                                |
| `ref` $bindable        | `HTMLDivElement`                                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                                                                                                                                                                         |
| `children`                          | `Snippet`- Snippet                                                                 | The children content to render.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                                                            |
| `child`                             | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };               | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                                                                                                                                                                  | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                                |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | The open state of the menu or submenu the element controls or belongs to.           |
| `data-menu-sub-content`                           | `''`                                                                                                                                                                                 | Present on the submenu content element. |

### ContextMenu.SubContentStatic

The submenu content displayed when the parent submenu menu is open. (Static/No Floating UI)

| Property                                                                         | Type                                                                                                                                                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onEscapeKeydown` | `function`- (event: KeyboardEvent) => void                                         | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default:  undefined`                                                                                                                                                                                                                    |
| `escapeKeydownBehavior`                        | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` |
| `onInteractOutside`                            | `function`- (event: PointerEvent) => void                                          | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default:  undefined`                                                                                                                                                                                                        |
| `onFocusOutside`                               | `function`- (event: FocusEvent) => void                                            | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default:  undefined`                                                                                                                                                                                                                                                  |
| `interactOutsideBehavior`                      | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close`  |
| `onOpenAutoFocus`                              | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is opened. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `onCloseAutoFocus`                             | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is closed. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `trapFocus`                                    | `boolean`                                                                                                                                                                                                          | Whether or not to trap the focus within the content when open.`Default: true`                                                                                                                                                                                                                                                                                                                                                      |
| `forceMount`                                   | `boolean`                                                                                                                                                                                                          | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                                                                                                                                                                                                                                                                 |
| `preventOverflowTextSelection`                 | `boolean`                                                                                                                                                                                                          | When `true`, prevents the text selection from overflowing the bounds of the element.`Default: true`                                                                                                                                                                                                                                                                                                                                |
| `dir`                                          | `enum`- 'ltr' \| 'rtl'                                                             | The reading direction of the app.`Default: 'ltr'`                                                                                                                                                                                                                                                                                                                                                                                  |
| `loop`                                         | `boolean`                                                                                                                                                                                                          | Whether or not to loop through the menu items when reaching the end of the list when using the keyboard.`Default: true`                                                                                                                                                                                                                                                                                                            |
| `ref` $bindable                   | `HTMLDivElement`                                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                                                                                                                                                                         |
| `children`                                     | `Snippet`- Snippet                                                                 | The children content to render.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                                                            |
| `child`                                        | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };               | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                                                                                                                                                                  | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                                |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | The open state of the menu or submenu the element controls or belongs to.           |
| `data-menu-sub-content`                           | `''`                                                                                                                                                                                 | Present on the submenu content element. |

----------------------------------------------------

# Date Field Documentation

Enables users to input specific dates within a designated field.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { DateField } from "bits-ui";
</script>
<DateField.Root>
  <div class="flex w-full max-w-[280px] flex-col gap-1.5">
    <DateField.Label class="block select-none text-sm font-medium"
      >Birthday</DateField.Label
    >
    <DateField.Input
      class="h-input rounded-input border-border-input bg-background text-foreground focus-within:border-border-input-hover focus-within:shadow-date-field-focus hover:border-border-input-hover data-invalid:border-destructive flex w-full select-none items-center border px-2 py-3 text-sm tracking-[0.01em] "
    >
      {#snippet children({ segments })}
        {#each segments as { part, value }}
          <div class="inline-block select-none">
            {#if part === "literal"}
              <DateField.Segment {part} class="text-muted-foreground p-1">
                {value}
              </DateField.Segment>
            {:else}
              <DateField.Segment
                {part}
                class="rounded-5px hover:bg-muted focus:bg-muted focus:text-foreground aria-[valuetext=Empty]:text-muted-foreground data-invalid:text-destructive focus-visible:ring-0! focus-visible:ring-offset-0! px-1 py-1"
              >
                {value}
              </DateField.Segment>
            {/if}
          </div>
        {/each}
      {/snippet}
    </DateField.Input>
  </div>
</DateField.Root>
```

##### Heads up!

Before diving into this component, it's important to understand how dates/times work in Bits UI. Please read the [Dates](/docs/dates) documentation to learn more!

## Overview

The `DateField` component is an alternative to the native `<input type="date">` element. It provides a more flexible and customizable way to select dates within a designated field.

## Structure

```svelte
<script lang="ts">
 import { DateField } from "$lib";
</script>
<DateField.Root>
 <DateField.Label>Check-in date</DateField.Label>
 <DateField.Input>
  {#snippet children({ segments })}
   {#each segments as { part, value }}
    <DateField.Segment {part}>
     {value}
    </DateField.Segment>
   {/each}
  {/snippet}
 </DateField.Input>
</DateField.Root>
```

## Reusable Components

It's recommended to use the `DateField` primitives to build your own custom date field component that can be used throughout your application.

The following example shows how you might create a reusable `MyDateField` component that can be used throughout your application. For style inspiration, reference the featured demo at the top of this page.

MyDateField.svelte

```svelte
<script lang="ts">
 import { DateField, type WithoutChildrenOrChild } from "bits-ui";
 type Props = WithoutChildrenOrChild<DateField.RootProps> & {
  labelText: string;
 };
 let { value, placeholder, name, ...restProps }: Props = $props();
</script>
<DateField.Root bind:value bind:placeholder {name} {...restProps}>
 <DateField.Label>{labelText}</DateField.Label>
 <DateField.Input>
  {#snippet children({ segments })}
   {#each segments as { part, value }}
    <DateField.Segment {part}>
     {value}
    </DateField.Segment>
   {/each}
  {/snippet}
 </DateField.Input>
</DateField.Root>
```

```svelte
<script lang="ts">
  import { DateField } from "bits-ui";
  let {
    labelText = "Select a date",
    value = $bindable(),
    placeholder = $bindable(),
    ...restProps
  }: DateField.RootProps & { labelText: string } = $props();
</script>
<DateField.Root bind:value bind:placeholder {...restProps}>
  <div class="flex w-fit min-w-[280px] flex-col gap-1.5">
    <DateField.Label class="block select-none text-sm font-medium"
      >{labelText}</DateField.Label
    >
    <DateField.Input
      class="h-input rounded-input border-border-input bg-background text-foreground focus-within:border-border-input-hover focus-within:shadow-date-field-focus hover:border-border-input-hover data-invalid:border-destructive flex w-full select-none items-center border px-2 py-3 text-sm tracking-[0.01em] "
    >
      {#snippet children({ segments })}
        {#each segments as { part, value }}
          <div class="inline-block select-none">
            {#if part === "literal"}
              <DateField.Segment {part} class="text-muted-foreground p-1">
                {value}
              </DateField.Segment>
            {:else}
              <DateField.Segment
                {part}
                class="rounded-5px hover:bg-muted focus:bg-muted focus:text-foreground aria-[valuetext=Empty]:text-muted-foreground data-invalid:text-destructive focus-visible:ring-0! focus-visible:ring-offset-0! px-1 py-1"
              >
                {value}
              </DateField.Segment>
            {/if}
          </div>
        {/each}
      {/snippet}
    </DateField.Input>
  </div>
</DateField.Root>
```

We'll be using this newly created `MyDateField` component in the following demos and examples to prevent repeating the same code, so be sure to reference it as you go through the documentation.

## Segments

A segment of the `DateField` represents a not only a specific part of the date, such as the day, month, year, hour, but can also reference a `"literal"` which is typically a separator between the different parts of the date, and varies based on the `locale`.

Notice that in the `MyDateField` component we created, we're styling the `DateField.Segment` components differently based on whether they are a `"literal"` or not.

## Placeholder

The `placeholder` prop for the `DateField.Root` component isn't what is displayed when the field is empty, but rather what date our field should start with when the user attempts to cycle through the segments. The placeholder can also be used to set a granularity for the date field, which will determine which type of `DateValue` object is used for the `value`.

By default, the `placeholder` will be set to the current date, and be of type `CalendarDate`. However, if we wanted this date field to also allow for selecting a time, we could set the placeholder to a `CalendarDateTime` object.

```svelte
<script lang="ts">
 import MyDateField from "$lib/components/MyDateField.svelte";
 import { CalendarDateTime } from "@internationalized/date";
</script>
<MyDateField placeholder={new CalendarDateTime(2024, 8, 3, 12, 30)} />
```

If we're collecting a date from the user where we want the timezone as well, we can use a `ZonedDateTime` object instead.

```svelte
<script lang="ts">
 import MyDateField from "$lib/components/MyDateField.svelte";
 import { now, getLocalTimeZone } from "@internationalized/date";
</script>
<MyDateField placeholder={now("America/New_York")} />
```

##### Leap Years!

If you're creating a date field for something like a birthday, ensure your placeholder is set in a leap year to ensure users born on a leap year will be able to select the correct date.

## Managing Placeholder State

This section covers how to manage the `placeholder` state of the Date Field.

### Two-Way Binding

Use `bind:placeholder` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { DateField } from "bits-ui";
 import { CalendarDateTime } from "@internationalized/date";
 let myPlaceholder = $state(new CalendarDateTime(2024, 8, 3, 12, 30));
</script>
<button onclick={() => (myPlaceholder = new CalendarDate(2024, 8, 3))}>
 Set placeholder to August 3rd, 2024
</button>
<DateField.Root bind:placeholder={myPlaceholder}>
</DateField.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { DateField } from "bits-ui";
 import type { DateValue } from "@internationalized/date";
 let myPlaceholder = $state<DateValue>();
 function getPlaceholder() {
  return myPlaceholder;
 }
 function setPlaceholder(newPlaceholder: DateValue) {
  myPlaceholder = newPlaceholder;
 }
</script>
<DateField.Root bind:placeholder={getPlaceholder, setPlaceholder}>
</DateField.Root>
```

## Managing Value State

This section covers how to manage the `value` state of the Date Field.

### Two-Way Binding

Use `bind:value` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { DateField } from "bits-ui";
 import { CalendarDateTime } from "@internationalized/date";
 let myValue = $state(new CalendarDateTime(2024, 8, 3, 12, 30));
</script>
<button onclick={() => (myValue = myValue.add({ days: 1 }))}> Add 1 day </button>
<DateField.Root bind:value={myValue}>
</DateField.Root>
```

### Fully Controlled

For complete control over the component's state, use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) to manage the value state externally.

```svelte
<script lang="ts">
 import { DateField } from "bits-ui";
 import type { DateValue } from "@internationalized/date";
 let myValue = $state<DateValue>();
 function getValue() {
  return myValue;
 }
 function setValue(newValue: DateValue) {
  myValue = newValue;
 }
</script>
<DateField.Root bind:value={getValue, setValue}>
</DateField.Root>
```

## Default Value

Often, you'll want to start the `DateField.Root` component with a default value. Likely this value will come from a database in the format of an ISO 8601 string. You can use the `parseDate` function from the `@internationalized/date` package to parse the string into a `CalendarDate` object.

+page.svelte

```svelte
<script lang="ts">
 import { DateField } from "bits-ui";
 import { parseDate } from "@internationalized/date";
 // this came from a database/API call
 const date = "2024-08-03";
 let value = $state(parseDate(date));
</script>
<DateField.Root {value}>
</DateField.Root>
```

Now our input is populated with the default value. In addition to the `parseDate` function, you can also use `parseDateTime` or `parseZonedDateTime` to parse the string into a `CalendarDateTime` or `ZonedDateTime` object respectively.

## Validation

### Minimum Value

You can set a minimum value for the `DateField.Root` component by using the `minValue` prop. If a user selects a date that is less than the minimum value, the date field will be marked as invalid.

```svelte
<script lang="ts">
 import MyDateField from "$lib/components/MyDateField.svelte";
 import { today, getLocalTimeZone } from "@internationalized/date";
 const todayDate = today(getLocalTimeZone());
 const yesterday = todayDate.subtract({ days: 1 });
</script>
<MyDateField minValue={todayDate} value={yesterday} />
```

In the example above, we're setting the minimum value to today, and the default value to yesterday. This causes the date field to be marked as invalid, and we can style it accordingly. If you adjust the date to be greater than the minimum value, the invalid state will be cleared.

### Maximum Value

You can set a maximum value for the `DateField.Root` component by using the `maxValue` prop. If a user selects a date that is greater than the maximum value, the date field will be marked as invalid.

```svelte
<script lang="ts">
 import MyDateField from "$lib/components/MyDateField.svelte";
 import { today, getLocalTimeZone } from "@internationalized/date";
 const todayDate = today(getLocalTimeZone());
 const tomorrow = todayDate.add({ days: 1 });
</script>
<MyDateField maxValue={todayDate} value={tomorrow} />
```

In the example above, we're setting the maximum value to today, and the default value to tomorrow. This causes the date field to be marked as invalid, and we can style it accordingly. If you adjust the date to be less than the maximum value, the invalid state will be cleared.

### Custom Validation

You can use the `validate` prop to provide a custom validation function for the date field. This function should return a string or array of strings as validation errors if the date is invalid, or undefined/nothing if the date is valid.

The strings are then passed to the `onInvalid` callback, which you can use to display an error message to the user.

```svelte
<script lang="ts">
 import MyDateField from "$lib/components/MyDateField.svelte";
 import { CalendarDate, type DateValue } from "@internationalized/date";
 const value = new CalendarDate(2024, 8, 2);
 function validate(date: DateValue) {
  return date.day === 1 ? "Date cannot be the first day of the month" : undefined;
 }
 function onInvalid(reason: "min" | "max" | "custom", msg?: string | string[]) {
  if (reason === "custom") {
   if (typeof msg === "string") {
    // do something with the error message
    console.log(msg);
    return;
   } else if (Array.isArray(msg)) {
    // do something with the error messages
    console.log(msg);
    return;
   }
   console.log("The date is invalid");
  } else if (reason === "min") {
   // let the user know that the date is too early.
   console.log("The date is too early.");
  } else if (reason === "max") {
   // let the user know that the date is too late.
   console.log("The date is too late.");
  }
 }
</script>
<MyDateField {validate} {value} {onInvalid} />
```

In the example above, we're setting the `isDateUnavailable` prop to a function that returns `true` for the first day of the month. Try selecting a date that is the first day of the month to see the date field marked as invalid.

## Granularity

The `granularity` prop sets the granularity of the date field, which determines which segments are rendered in the date field. The `granularity` can be set to either `'day'`, `'hour'`, `'minute'`, or `'second'`.

```svelte
<script lang="ts">
 import MyDateField from "$lib/components/MyDateField.svelte";
 import { CalendarDateTime } from "@internationalized/date";
 const value = new CalendarDateTime(2024, 8, 2, 12, 30);
</script>
<MyDateField granularity="second" {value} />
```

In the example above, we're setting the granularity to `'second'`, which means that the date field will include an additional segment for the seconds.

## Localization

You can use the `locale` prop to set the locale of the date field. This will affect the formatting of the date field's segments and placeholders.

```svelte
<script lang="ts">
 import MyDateField from "$lib/components/MyDateField.svelte";
</script>
<MyDateField locale="de" />
```

## API Reference

### DateField.Root

The root date field component.

| Property                                                                                      | Type                                                                                                                                                                                                                                                                                                                                                     | Description                                                                                                                                                                                                                                                                                           |
| -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` $bindable | `DateValue`- import type { CalendarDate, CalendarDateTime, ZonedDateTime } from "@internationalized/date"; type DateValue = CalendarDate \| CalendarDateTime \| ZonedDateTime | The selected date.`Default:  undefined`                                                                                                                                                                                                                              |
| `onValueChange`                                             | `function`- (value: DateValue) => void                                                                                                                                        | A function that is called when the selected date changes.`Default:  undefined`                                                                                                                                                                                       |
| `placeholder` $bindable                        | `DateValue`- import type { CalendarDate, CalendarDateTime, ZonedDateTime } from "@internationalized/date"; type DateValue = CalendarDate \| CalendarDateTime \| ZonedDateTime | The placeholder date, which is used to determine what date to start the segments from when no value exists.`Default:  undefined`                                                                                                                                     |
| `onPlaceholderChange`                                       | `function`- (value: DateValue) => void                                                                                                                                        | A function that is called when the placeholder date changes.`Default:  undefined`                                                                                                                                                                                    |
| `required`                                                  | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not the date field is required.`Default: false`                                                                                                                                                                                                              |
| `validate`                                                  | `function`- (value: DateValue) => boolean                                                                                                                                     | A function that returns whether or not a date is unavailable.`Default:  undefined`                                                                                                                                                                                   |
| `onInvalid`                                                 | `function`- (value: DateValue) => void                                                                                                                                        | A callback fired when the date field's value is invalid.`Default:  undefined`                                                                                                                                                                                        |
| `errorMessageId`                                            | `string`                                                                                                                                                                                                                                                                                                      | The `id` of the element which contains the error messages for the date field when the date is invalid.`Default:  undefined`                                                                                                                                          |
| `hourCycle`                                                 | `enum`- '12' \| '24'                                                                                                                                                          | The hour cycle to use for formatting times. Defaults to the locale preference`Default:  undefined`                                                                                                                                                                   |
| `granularity`                                               | `enum`- 'day' \| 'hour' \| 'minute' \| 'second'                                                                                                                               | The granularity to use for formatting the field. Defaults to `'day'` if a `CalendarDate` is provided, otherwise defaults to `'minute'`. The field will render segments for each part of the date up to and including the specified granularity.`Default:  undefined` |
| `hideTimeZone`                                              | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not to hide the time zone segment of the field.`Default: false`                                                                                                                                                                                              |
| `maxValue`                                                  | `DateValue`- import type { CalendarDate, CalendarDateTime, ZonedDateTime } from "@internationalized/date"; type DateValue = CalendarDate \| CalendarDateTime \| ZonedDateTime | The maximum valid date that can be entered.`Default:  undefined`                                                                                                                                                                                                     |
| `minValue`                                                  | `DateValue`- import type { CalendarDate, CalendarDateTime, ZonedDateTime } from "@internationalized/date"; type DateValue = CalendarDate \| CalendarDateTime \| ZonedDateTime | The minimum valid date that can be entered.`Default:  undefined`                                                                                                                                                                                                     |
| `locale`                                                    | `string`                                                                                                                                                                                                                                                                                                      | The locale to use for formatting dates.`Default: 'en-US'`                                                                                                                                                                                                               |
| `disabled`                                                  | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not the accordion is disabled.`Default: false`                                                                                                                                                                                                               |
| `readonly`                                                  | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not the field is readonly.`Default: false`                                                                                                                                                                                                                   |
| `readonlySegments`                                          | `EditableSegmentPart[]`- "day" \| "month" \| "year" \| "hour" \| "minute" \| "second" \| "dayPeriod"                                                                          | An array of segments that should be readonly, which prevent user input on them.`Default:  undefined`                                                                                                                                                                 |
| `children`                                                  | `Snippet`                                                                                                                                                                                                                                                                                                     | The children content to render.`Default:  undefined`                                                                                                                                                                             |

### DateField.Input

The container for the segments of the date field.

| Property                                                              | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | `string`                                                                                                                                                                                             | The name of the date field used for form submission. If provided, a hidden input element will be rendered alongside the date field.`Default:  undefined`                       |
| `ref` $bindable        | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                          | `Snippet`- Snippet                                                   | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                             | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                               | Value         | Description                                                                                |
| ------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `data-invalid` | `''` | Present on the element when the field is invalid.                   |
| `data-disabled`                                     | `''` | Present on the element when the field is disabled.                  |
| `data-date-field-input`                             | `''` | Present on the element. |

### DateField.Segment

A segment of the date field.

| Property                                                                                    | Type                                                                                                                                                                                                                                                                                                  | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `part` required | `SegmentPart`- "month" \| "day" \| "year" \| "hour" \| "minute" \| "second" \| "dayPeriod" \| "timeZoneName" \| "literal"; | The part of the date to render.`Default:  undefined`                                                                                                                           |
| `ref` $bindable                              | `HTMLDivElement`                                                                                                                                                                                                                                           | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                                                                                  | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };                                                       | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                               | Value                                                                                                      | Description                                                                                |
| ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `data-invalid` | `''`                                                                                              | Present on the element when the field is invalid                    |
| `data-disabled`                                     | `''`                                                                                              | Present on the element when the field is disabled                   |
| `data-readonly`                                     | `''`                                                                                              | Present on the element when the field or segment is readonly        |
| `data-segment`                                      | `enum` | The part of the date to render.                                     |
| `data-date-field-segment`                           | `''`                                                                                              | Present on the element. |

### DateField.Label

The label for the date field.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLSpanElement`                                                                                                                                                                                    | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                               | Value         | Description                                                                                |
| ------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `data-invalid` | `''` | Present on the element when the field is invalid                    |
| `data-disabled`                                     | `''` | Present on the element when the field is disabled                   |
| `data-date-field-label`                             | `''` | Present on the element. |

----------------------------------------------------

# Date Picker Documentation

Facilitates the selection of dates through an input and calendar-based interface.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { DatePicker } from "bits-ui";
  import CalendarBlank from "phosphor-svelte/lib/CalendarBlank";
  import CaretLeft from "phosphor-svelte/lib/CaretLeft";
  import CaretRight from "phosphor-svelte/lib/CaretRight";
</script>
<DatePicker.Root weekdayFormat="short" fixedWeeks={true}>
  <div class="flex w-full max-w-[232px] flex-col gap-1.5">
    <DatePicker.Label class="block select-none text-sm font-medium"
      >Birthday</DatePicker.Label
    >
    <DatePicker.Input
      class="h-input rounded-input border-border-input bg-background text-foreground focus-within:border-border-input-hover focus-within:shadow-date-field-focus hover:border-border-input-hover flex w-full max-w-[232px] select-none items-center border px-2 py-3 text-sm tracking-[0.01em]"
    >
      {#snippet children({ segments })}
        {#each segments as { part, value }}
          <div class="inline-block select-none">
            {#if part === "literal"}
              <DatePicker.Segment {part} class="text-muted-foreground p-1">
                {value}
              </DatePicker.Segment>
            {:else}
              <DatePicker.Segment
                {part}
                class="rounded-5px hover:bg-muted focus:bg-muted focus:text-foreground aria-[valuetext=Empty]:text-muted-foreground focus-visible:ring-0! focus-visible:ring-offset-0! px-1 py-1"
              >
                {value}
              </DatePicker.Segment>
            {/if}
          </div>
        {/each}
        <DatePicker.Trigger
          class="text-foreground/60 hover:bg-muted active:bg-dark-10 ml-auto inline-flex size-8 items-center justify-center rounded-[5px] transition-all"
        >
          <CalendarBlank class="size-6" />
        </DatePicker.Trigger>
      {/snippet}
    </DatePicker.Input>
    <DatePicker.Content sideOffset={6} class="z-50">
      <DatePicker.Calendar
        class="border-dark-10 bg-background-alt shadow-popover rounded-[15px] border p-[22px]"
      >
        {#snippet children({ months, weekdays })}
          <DatePicker.Header class="flex items-center justify-between">
            <DatePicker.PrevButton
              class="rounded-9px bg-background-alt hover:bg-muted inline-flex size-10 items-center justify-center transition-all active:scale-[0.98]"
            >
              <CaretLeft class="size-6" />
            </DatePicker.PrevButton>
            <DatePicker.Heading class="text-[15px] font-medium" />
            <DatePicker.NextButton
              class="rounded-9px bg-background-alt hover:bg-muted inline-flex size-10 items-center justify-center transition-all active:scale-[0.98]"
            >
              <CaretRight class="size-6" />
            </DatePicker.NextButton>
          </DatePicker.Header>
          <div
            class="flex flex-col space-y-4 pt-4 sm:flex-row sm:space-x-4 sm:space-y-0"
          >
            {#each months as month}
              <DatePicker.Grid
                class="w-full border-collapse select-none space-y-1"
              >
                <DatePicker.GridHead>
                  <DatePicker.GridRow class="mb-1 flex w-full justify-between">
                    {#each weekdays as day}
                      <DatePicker.HeadCell
                        class="text-muted-foreground font-normal! w-10 rounded-md text-xs"
                      >
                        <div>{day.slice(0, 2)}</div>
                      </DatePicker.HeadCell>
                    {/each}
                  </DatePicker.GridRow>
                </DatePicker.GridHead>
                <DatePicker.GridBody>
                  {#each month.weeks as weekDates}
                    <DatePicker.GridRow class="flex w-full">
                      {#each weekDates as date}
                        <DatePicker.Cell
                          {date}
                          month={month.value}
                          class="p-0! relative size-10 text-center text-sm"
                        >
                          <DatePicker.Day
                            class="rounded-9px text-foreground hover:border-foreground data-selected:bg-foreground data-disabled:text-foreground/30 data-selected:text-background data-unavailable:text-muted-foreground data-disabled:pointer-events-none data-outside-month:pointer-events-none data-selected:font-medium data-unavailable:line-through group relative inline-flex size-10 items-center justify-center whitespace-nowrap border border-transparent bg-transparent p-0 text-sm font-normal transition-all"
                          >
                            <div
                              class="bg-foreground group-data-selected:bg-background group-data-today:block absolute top-[5px] hidden size-1 rounded-full transition-all"
                            ></div>
                            {date.day}
                          </DatePicker.Day>
                        </DatePicker.Cell>
                      {/each}
                    </DatePicker.GridRow>
                  {/each}
                </DatePicker.GridBody>
              </DatePicker.Grid>
            {/each}
          </div>
        {/snippet}
      </DatePicker.Calendar>
    </DatePicker.Content>
  </div>
</DatePicker.Root>
```

##### Heads up!

Before diving into this component, it's important to understand how dates/times work in Bits UI. Please read the [Dates](/docs/dates) documentation to learn more!

## Structure

```svelte
<script lang="ts">
 import { DatePicker } from "bits-ui";
</script>
<DatePicker.Root>
 <DatePicker.Label />
 <DatePicker.Input>
  {#snippet children({ segments })}
   {#each segments as { part, value }}
    <DatePicker.Segment {part}>
     {value}
    </DatePicker.Segment>
   {/each}
   <DatePicker.Trigger />
  {/snippet}
 </DatePicker.Input>
 <DatePicker.Content>
  <DatePicker.Calendar>
   {#snippet children({ months, weekdays })}
    <DatePicker.Header>
     <DatePicker.PrevButton />
     <DatePicker.Heading />
     <DatePicker.NextButton />
    </DatePicker.Header>
    {#each months as month}
     <DatePicker.Grid>
      <DatePicker.GridHead>
       <DatePicker.GridRow>
        {#each weekdays as day}
         <DatePicker.HeadCell>
          {day}
         </DatePicker.HeadCell>
        {/each}
       </DatePicker.GridRow>
      </DatePicker.GridHead>
      <DatePicker.GridBody>
       {#each month.weeks as weekDates}
        <DatePicker.GridRow>
         {#each weekDates as date}
          <DatePicker.Cell {date} month={month.value}>
           <DatePicker.Day />
          </DatePicker.Cell>
         {/each}
        </DatePicker.GridRow>
       {/each}
      </DatePicker.GridBody>
     </DatePicker.Grid>
    {/each}
   {/snippet}
  </DatePicker.Calendar>
 </DatePicker.Content>
</DatePicker.Root>
```

## Managing Placeholder State

This section covers how to manage the `placeholder` state of the component.

### Two-Way Binding

Use `bind:placeholder` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { DatePicker } from "bits-ui";
 import { CalendarDateTime } from "@internationalized/date";
 let myPlaceholder = $state();
</script>
<button
 onclick={() => {
  myPlaceholder = new CalendarDateTime(2024, 8, 3, 12, 30);
 }}
>
 Set placeholder to August 3rd, 2024
</button>
<DatePicker.Root bind:placeholder={myPlaceholder}>
</DatePicker.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { DatePicker } from "bits-ui";
 import type { DateValue } from "@internationalized/date";
 let myPlaceholder = $state<DateValue>();
 function getPlaceholder() {
  return myPlaceholder;
 }
 function setPlaceholder(newPlaceholder: DateValue) {
  myPlaceholder = newPlaceholder;
 }
</script>
<DatePicker.Root bind:placeholder={getPlaceholder, setPlaceholder}>
</DatePicker.Root>
```

## Managing Value State

This section covers how to manage the `value` state of the component.

### Two-Way Binding

Use `bind:value` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { DatePicker } from "bits-ui";
 import { CalendarDateTime } from "@internationalized/date";
 let myValue = $state(new CalendarDateTime(2024, 8, 3, 12, 30));
</script>
<button onclick={() => (myValue = myValue.add({ days: 1 }))}> Add 1 day </button>
<DatePicker.Root bind:value={myValue}>
</DatePicker.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { DatePicker } from "bits-ui";
 import type { DateValue } from "@internationalized/date";
 let myValue = $state<DateValue>();
 function getValue() {
  return myValue;
 }
 function setValue(newValue: DateValue) {
  myValue = newValue;
 }
</script>
<DatePicker.Root bind:value={getValue, setValue}>
</DatePicker.Root>
```

## Managing Open State

This section covers how to manage the `open` state of the component.

### Two-Way Binding

Use `bind:open` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { DatePicker } from "bits-ui";
 let isOpen = $state(false);
</script>
<button onclick={() => (isOpen = true)}>Open DatePicker</button>
<DatePicker.Root bind:open={isOpen}>
</DatePicker.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { DatePicker } from "bits-ui";
 let myOpen = $state(false);
 function getOpen() {
  return myOpen;
 }
 function setOpen(newOpen: boolean) {
  myOpen = newOpen;
 }
</script>
<DatePicker.Root bind:open={getOpen, setOpen}>
</DatePicker.Root>
```

## Customization

The `DatePicker` component is made up of three other Bits UI components: [Date Field](/docs/components/date-field), [Calendar](/docs/components/calendar), and [Popover](/docs/components/popover).

You can check out the documentation for each of these components to learn more about their customization options, each of which can be used to customize the `DatePicker` component.

## API Reference

### DatePicker.Root

The root date picker component.

| Property                                                                                      | Type                                                                                                                                                                                                                                                                                                                                                     | Description                                                                                                                                                                                                                                                                                           |
| -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` $bindable | `union`- DateValue \| DateValue\[]                                                                                                                                            | The selected date(s). If `type` is `'single'`, this will be a `DateValue`. If `type` is `'multiple'`, this will be an array of `DateValue`s.`Default:  undefined`                                                                                                    |
| `onValueChange`                                             | `function`- (value: DateValue) => void \| (value: DateValue\[]) => void                                                                                                       | A function that is called when the selected date changes.`Default:  undefined`                                                                                                                                                                                       |
| `open` $bindable                               | `boolean`                                                                                                                                                                                                                                                                                                     | The open state of the popover content.`Default: false`                                                                                                                                                                                                                  |
| `onOpenChange`                                              | `function`- (open: boolean) => void                                                                                                                                           | A callback that fires when the open state changes.`Default:  undefined`                                                                                                                                                                                              |
| `placeholder`                                               | `DateValue`- import type { CalendarDate, CalendarDateTime, ZonedDateTime } from "@internationalized/date"; type DateValue = CalendarDate \| CalendarDateTime \| ZonedDateTime | The placeholder date, which is used to determine what month to display when no date is selected. This updates as the user navigates the calendar, and can be used to programmatically control the calendar's view.`Default:  undefined`                              |
| `onPlaceholderChange`                                       | `function`- (date: DateValue) => void                                                                                                                                         | A function that is called when the placeholder date changes.`Default:  undefined`                                                                                                                                                                                    |
| `isDateUnavailable`                                         | `function`- (date: DateValue) => boolean                                                                                                                                      | A function that returns whether or not a date is unavailable.`Default:  undefined`                                                                                                                                                                                   |
| `isDateDisabled`                                            | `function`- (date: DateValue) => boolean                                                                                                                                      | A function that returns whether or not a date is disabled.`Default:  undefined`                                                                                                                                                                                      |
| `validate`                                                  | `function`- (value: DateValue) => boolean                                                                                                                                     | A function that returns whether or not a date is unavailable.`Default:  undefined`                                                                                                                                                                                   |
| `onInvalid`                                                 | `function`- (value: DateValue) => void                                                                                                                                        | A callback fired when the date field's value is invalid.`Default:  undefined`                                                                                                                                                                                        |
| `required`                                                  | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not the date field is required.`Default: false`                                                                                                                                                                                                              |
| `errorMessageId`                                            | `string`                                                                                                                                                                                                                                                                                                      | The `id` of the element which contains the error messages for the date field when the date is invalid.`Default:  undefined`                                                                                                                                          |
| `readonlySegments`                                          | `EditableSegmentPart[]`- "day" \| "month" \| "year" \| "hour" \| "minute" \| "second" \| "dayPeriod"                                                                          | An array of segments that should be readonly, which prevent user input on them.`Default:  undefined`                                                                                                                                                                 |
| `disableDaysOutsideMonth`                                   | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not to disable days outside the current month.`Default: false`                                                                                                                                                                                               |
| `closeOnDateSelect`                                         | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not to close the popover when a date is selected.`Default: true`                                                                                                                                                                                             |
| `pagedNavigation`                                           | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not to use paged navigation for the calendar. Paged navigation causes the previous and next buttons to navigate by the number of months displayed at once, rather than by one month.`Default: false`                                                         |
| `preventDeselect`                                           | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not to prevent the user from deselecting a date without selecting another date first.`Default: false`                                                                                                                                                        |
| `weekStartsOn`                                              | `number`                                                                                                                                                                                                                                                                                                      | The day of the week to start the calendar on. 0 is Sunday, 1 is Monday, etc.`Default: 0`                                                                                                                                                                                |
| `weekdayFormat`                                             | `enum`- 'narrow' \| 'short' \| 'long'                                                                                                                                         | The format to use for the weekday strings provided via the `weekdays` slot prop.`Default: 'narrow'`                                                                                                                                                                     |
| `calendarLabel`                                             | `string`                                                                                                                                                                                                                                                                                                      | The accessible label for the calendar.`Default:  undefined`                                                                                                                                                                                                          |
| `fixedWeeks`                                                | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not to always display 6 weeks in the calendar.`Default: false`                                                                                                                                                                                               |
| `maxValue`                                                  | `DateValue`- import type { CalendarDate, CalendarDateTime, ZonedDateTime } from "@internationalized/date"; type DateValue = CalendarDate \| CalendarDateTime \| ZonedDateTime | The maximum date that can be selected.`Default:  undefined`                                                                                                                                                                                                          |
| `minValue`                                                  | `DateValue`- import type { CalendarDate, CalendarDateTime, ZonedDateTime } from "@internationalized/date"; type DateValue = CalendarDate \| CalendarDateTime \| ZonedDateTime | The minimum date that can be selected.`Default:  undefined`                                                                                                                                                                                                          |
| `locale`                                                    | `string`                                                                                                                                                                                                                                                                                                      | The locale to use for formatting dates.`Default: 'en'`                                                                                                                                                                                                                  |
| `numberOfMonths`                                            | `number`                                                                                                                                                                                                                                                                                                      | The number of months to display at once.`Default: 1`                                                                                                                                                                                                                    |
| `disabled`                                                  | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not the accordion is disabled.`Default: false`                                                                                                                                                                                                               |
| `readonly`                                                  | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not the field is readonly.`Default: false`                                                                                                                                                                                                                   |
| `hourCycle`                                                 | `enum`- '12' \| '24'                                                                                                                                                          | The hour cycle to use for formatting times. Defaults to the locale preference`Default:  undefined`                                                                                                                                                                   |
| `granularity`                                               | `enum`- 'day' \| 'hour' \| 'minute' \| 'second'                                                                                                                               | The granularity to use for formatting the field. Defaults to `'day'` if a `CalendarDate` is provided, otherwise defaults to `'minute'`. The field will render segments for each part of the date up to and including the specified granularity.`Default:  undefined` |
| `hideTimeZone`                                              | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not to hide the time zone segment of the field.`Default: false`                                                                                                                                                                                              |
| `initialFocus`                                              | `boolean`                                                                                                                                                                                                                                                                                                     | If `true`, the calendar will focus the selected day, today, or the first day of the month in that order depending on what is visible when the calendar is mounted.`Default: false`                                                                                      |
| `children`                                                  | `Snippet`                                                                                                                                                                                                                                                                                                     | The children content to render.`Default:  undefined`                                                                                                                                                                             |

| Data Attribute                               | Value         | Description                                                                                     |
| ------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-invalid` | `''` | Present on the root element when the calendar is invalid.                |
| `data-disabled`                                     | `''` | Present on the root element when the calendar is disabled.               |
| `data-readonly`                                     | `''` | Present on the root element when the calendar is readonly.               |
| `data-date-picker-root`                             | `''` | Present on the root element. |

### DatePicker.Label

The label for the date field.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLSpanElement`                                                                                                                                                                                    | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                               | Value         | Description                                                                                |
| ------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `data-invalid` | `''` | Present on the element when the field is invalid                    |
| `data-disabled`                                     | `''` | Present on the element when the field is disabled                   |
| `data-date-field-label`                             | `''` | Present on the element. |

### DatePicker.Input

The field input component which contains the segments of the date field.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                                   |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                      |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                                         |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                   |
| `name`                                                    | `string`                                                                                                                                                                                             | The name of the date field used for form submission. If provided, a hidden input element will be rendered alongside the date field.`Default:  undefined` |

| Data Attribute                               | Value         | Description                                                                                |
| ------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `data-invalid` | `''` | Present on the element when the field is invalid.                   |
| `data-disabled`                                     | `''` | Present on the element when the field is disabled.                  |
| `data-date-field-input`                             | `''` | Present on the element. |

### DatePicker.Segment

A segment of the date field.

| Property                                                                                    | Type                                                                                                                                                                                                                                                                                                  | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `part` required | `SegmentPart`- "month" \| "day" \| "year" \| "hour" \| "minute" \| "second" \| "dayPeriod" \| "timeZoneName" \| "literal"; | The part of the date to render.`Default:  undefined`                                                                                                                           |
| `ref` $bindable                              | `HTMLDivElement`                                                                                                                                                                                                                                           | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                                                                                  | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };                                                       | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                               | Value                                                                                                      | Description                                                                                |
| ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `data-invalid` | `''`                                                                                              | Present on the element when the field is invalid                    |
| `data-disabled`                                     | `''`                                                                                              | Present on the element when the field is disabled                   |
| `data-readonly`                                     | `''`                                                                                              | Present on the element when the field or segment is readonly        |
| `data-segment`                                      | `enum` | The part of the date to render.                                     |
| `data-date-field-segment`                           | `''`                                                                                              | Present on the element. |

### DatePicker.Trigger

A component which toggles the opening and closing of the popover on press.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                        |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | Whether the popover is open or closed.                                      |
| `data-popover-trigger`                            | `''`                                                                                                                                                                                 | Present on the trigger element. |

### DatePicker.Content

The contents of the popover which are displayed when the popover is open.

| Property                                                              | Type                                                                                                                                                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `side` | `enum`- 'top' \| 'bottom' \| 'left' \| 'right'                                     | The preferred side of the anchor to render the floating element against when open. Will be reversed when collisions occur.`Default: bottom`                                                                                                                                                                                                                                                                                        |
| `sideOffset`                        | `number`                                                                                                                                                                                                           | The distance in pixels from the anchor to the floating element.`Default: 0`                                                                                                                                                                                                                                                                                                                                                        |
| `align`                             | `enum`- 'start' \| 'center' \| 'end'                                               | The preferred alignment of the anchor to render the floating element against when open. This may change when collisions occur.`Default: start`                                                                                                                                                                                                                                                                                     |
| `alignOffset`                       | `number`                                                                                                                                                                                                           | The distance in pixels from the anchor to the floating element.`Default: 0`                                                                                                                                                                                                                                                                                                                                                        |
| `arrowPadding`                      | `number`                                                                                                                                                                                                           | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0`                                                                                                                                                                                                                                                                                                  |
| `avoidCollisions`                   | `boolean`                                                                                                                                                                                                          | When `true`, overrides the `side` and `align` options to prevent collisions with the boundary edges.`Default: true`                                                                                                                                                                                                                                                                                                                |
| `collisionBoundary`                 | `union`- Element \| null                                                           | A boundary element or array of elements to check for collisions against.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                   |
| `collisionPadding`                  | `union`- number \| Partial\&lt;Record\&lt;Side, number\&gt;\&gt;                   | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0`                                                                                                                                                                                                                                                                                                  |
| `sticky`                            | `enum`- 'partial' \| 'always'                                                      | The sticky behavior on the align axis. `'partial'` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst `'always'` will keep the content in the boundary regardless.`Default: partial`                                                                                                                                                                                        |
| `hideWhenDetached`                  | `boolean`                                                                                                                                                                                                          | When `true`, hides the content when it is detached from the DOM. This is useful for when you want to hide the content when the user scrolls away.`Default: true`                                                                                                                                                                                                                                                                   |
| `updatePositionStrategy`            | `enum`- 'optimized' \| 'always'                                                    | The strategy to use when updating the position of the content. When `'optimized'` the content will only be repositioned when the trigger is in the viewport. When `'always'` the content will be repositioned whenever the position changes.`Default: optimized`                                                                                                                                                                   |
| `strategy`                          | `enum`- 'fixed' \| 'absolute'                                                      | The positioning strategy to use for the floating element. When `'fixed'` the element will be positioned relative to the viewport. When `'absolute'` the element will be positioned relative to the nearest positioned ancestor.`Default: fixed`                                                                                                                                                                                    |
| `preventScroll`                     | `boolean`                                                                                                                                                                                                          | When `true`, prevents the body from scrolling when the content is open. This is useful when you want to use the content as a modal.`Default: false`                                                                                                                                                                                                                                                                                |
| `customAnchor`                      | `union`- string \| HTMLElement \| Measurable \| null                               | Use an element other than the trigger to anchor the content to. If provided, the content will be anchored to the provided element instead of the trigger.`Default: null`                                                                                                                                                                                                                                                           |
| `onInteractOutside`                 | `function`- (event: PointerEvent) => void                                          | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default:  undefined`                                                                                                                                                                                                        |
| `onFocusOutside`                    | `function`- (event: FocusEvent) => void                                            | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default:  undefined`                                                                                                                                                                                                                                                  |
| `interactOutsideBehavior`           | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close`  |
| `onEscapeKeydown`                   | `function`- (event: KeyboardEvent) => void                                         | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default:  undefined`                                                                                                                                                                                                                    |
| `escapeKeydownBehavior`             | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` |
| `onOpenAutoFocus`                   | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is opened. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `onCloseAutoFocus`                  | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is closed. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `trapFocus`                         | `boolean`                                                                                                                                                                                                          | Whether or not to trap the focus within the content when open.`Default: true`                                                                                                                                                                                                                                                                                                                                                      |
| `preventOverflowTextSelection`      | `boolean`                                                                                                                                                                                                          | When `true`, prevents the text selection from overflowing the bounds of the element.`Default: true`                                                                                                                                                                                                                                                                                                                                |
| `forceMount`                        | `boolean`                                                                                                                                                                                                          | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                                                                                                                                                                                                                                                                 |
| `dir`                               | `enum`- 'ltr' \| 'rtl'                                                             | The reading direction of the app.`Default: 'ltr'`                                                                                                                                                                                                                                                                                                                                                                                  |
| `ref` $bindable        | `HTMLDivElement`                                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                                                                                                                                                                         |
| `children`                          | `Snippet`                                                                                                                                                                                                          | The children content to render.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                                                            |
| `child`                             | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };               | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                                                                                                                                                                  | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                        |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | Whether the popover is open or closed.                                      |
| `data-popover-content`                            | `''`                                                                                                                                                                                 | Present on the content element. |

| CSS Variable                                                            | Description                                                                                                   |
| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--bits-popover-content-transform-origin` | The transform origin of the popover content element.                                   |
| `--bits-popover-content-available-width`                                       | The available width of the popover content element.                                    |
| `--bits-popover-content-available-height`                                      | The available height of the popover content element.                                   |
| `--bits-popover-anchor-width`                                                  | The width of the popover trigger element.                                              |
| `--bits-popover-anchor-height`                                                 | The height of the popover trigger element. |

### DatePicker.Calendar

The calendar component containing the grids of dates.

| Data Attribute                               | Value         | Description                                                                                         |
| ------------------------------------------------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-invalid` | `''` | Present on the calendar element when the calendar is invalid.                |
| `data-disabled`                                     | `''` | Present on the calendar element when the calendar is disabled.               |
| `data-readonly`                                     | `''` | Present on the calendar element when the calendar is readonly.               |
| `data-calendar-root`                                | `''` | Present on the calendar element. |

### DatePicker.Header

The header of the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLElement`                                                                                                                                                                                        | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                       |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the header element when the calendar is disabled.               |
| `data-readonly`                                      | `''` | Present on the header element when the calendar is readonly.               |
| `data-calendar-header`                               | `''` | Present on the header element. |

### DatePicker.PrevButton

The previous button of the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                             |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the prev button element when the calendar or this button is disabled. |
| `data-calendar-prev-button`                          | `''` | Present on the prev button element.  |

### DatePicker.Heading

The heading of the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                        |
| -------------------------------------------------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the heading element when the calendar is disabled.               |
| `data-readonly`                                      | `''` | Present on the heading element when the calendar is readonly.               |
| `data-calendar-heading`                              | `''` | Present on the heading element. |

### DatePicker.NextButton

The next button of the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                             |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the next button element when the calendar or this button is disabled. |
| `data-calendar-next-button`                          | `''` | Present on the next button element.  |

### DatePicker.Grid

The grid of dates in the calendar, typically representing a month.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLTableElement`                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                     |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the grid element when the calendar is disabled.               |
| `data-readonly`                                      | `''` | Present on the grid element when the calendar is readonly.               |
| `data-calendar-grid`                                 | `''` | Present on the grid element. |

### DatePicker.GridRow

A row in the grid of dates in the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLTableRowElement`                                                                                                                                                                                | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                         |
| -------------------------------------------------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the grid row element when the calendar is disabled.               |
| `data-readonly`                                      | `''` | Present on the grid row element when the calendar is readonly.               |
| `data-calendar-grid-row`                             | `''` | Present on the grid row element. |

### DatePicker.GridHead

The head of the grid of dates in the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLTableSectionElement`                                                                                                                                                                            | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                          |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the grid head element when the calendar is disabled.               |
| `data-readonly`                                      | `''` | Present on the grid head element when the calendar is readonly.               |
| `data-calendar-grid-head`                            | `''` | Present on the grid head element. |

### DatePicker.HeadCell

A cell in the head of the grid of dates in the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLTableCellElement`                                                                                                                                                                               | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                          |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the head cell element when the calendar is disabled.               |
| `data-readonly`                                      | `''` | Present on the head cell element when the calendar is readonly.               |
| `data-calendar-head-cell`                            | `''` | Present on the head cell element. |

### DatePicker.GridBody

The body of the grid of dates in the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLTableSectionElement`                                                                                                                                                                            | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                          |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the grid element when the calendar is disabled.                    |
| `data-readonly`                                      | `''` | Present on the grid element when the calendar is readonly.                    |
| `data-calendar-grid-body`                            | `''` | Present on the grid body element. |

### DatePicker.Cell

A cell in the calendar grid.

| Property                                                              | Type                                                                                                                                                                                                                                                                                                                                                     | Description                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `date` | `DateValue`- import type { CalendarDate, CalendarDateTime, ZonedDateTime } from "@internationalized/date"; type DateValue = CalendarDate \| CalendarDateTime \| ZonedDateTime | The date for the cell.`Default:  undefined`                                                                                                                                    |
| `month`                             | `DateValue`- import type { CalendarDate, CalendarDateTime, ZonedDateTime } from "@internationalized/date"; type DateValue = CalendarDate \| CalendarDateTime \| ZonedDateTime | The current month the date is being displayed in.`Default:  undefined`                                                                                                         |
| `ref` $bindable        | `HTMLTableCellElement`                                                                                                                                                                                                                                                                                        | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                          | `Snippet`                                                                                                                                                                                                                                                                                                     | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                             | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };                                                                                                          | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                     |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present when the day is disabled.                                        |
| `data-unavailable`                                   | `''` | Present when the day is unavailable.                                     |
| `data-today`                                         | `''` | Present when the day is today.                                           |
| `data-outside-month`                                 | `''` | Present when the day is outside the current month.                       |
| `data-outside-visible-months`                        | `''` | Present when the day is outside the visible months.                      |
| `data-focused`                                       | `''` | Present when the day is focused.                                         |
| `data-selected`                                      | `''` | Present when the day is selected.                                        |
| `data-value`                                         | `''` | The date in the format "YYYY-MM-DD".                                     |
| `data-calendar-cell`                                 | `''` | Present on the cell element. |

### DatePicker.Day

A day in the calendar grid.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                    |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present when the day is disabled.                                       |
| `data-unavailable`                                   | `''` | Present when the day is unavailable.                                    |
| `data-today`                                         | `''` | Present when the day is today.                                          |
| `data-outside-month`                                 | `''` | Present when the day is outside the current month.                      |
| `data-outside-visible-months`                        | `''` | Present when the day is outside the visible months.                     |
| `data-focused`                                       | `''` | Present when the day is focused.                                        |
| `data-selected`                                      | `''` | Present when the day is selected.                                       |
| `data-value`                                         | `''` | The date in the format "YYYY-MM-DD".                                    |
| `data-calendar-day`                                  | `''` | Present on the day element. |

----------------------------------------------------

# Date Range Field Documentation

Allows users to input a range of dates within a designated field.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { DateRangeField } from "bits-ui";
</script>
<DateRangeField.Root class="group flex w-full max-w-[320px] flex-col gap-1.5">
  <DateRangeField.Label class="block select-none text-sm font-medium">
    Hotel dates
  </DateRangeField.Label>
  <div
    class="h-input rounded-input border-border-input bg-background text-foreground focus-within:border-border-input-hover focus-within:shadow-date-field-focus hover:border-border-input-hover group-data-invalid:border-destructive flex w-full select-none items-center border px-2 py-3 text-sm tracking-[0.01em]"
  >
    {#each ["start", "end"] as const as type}
      <DateRangeField.Input {type}>
        {#snippet children({ segments })}
          {#each segments as { part, value }}
            <div class="inline-block select-none">
              {#if part === "literal"}
                <DateRangeField.Segment
                  {part}
                  class="text-muted-foreground p-1"
                >
                  {value}
                </DateRangeField.Segment>
              {:else}
                <DateRangeField.Segment
                  {part}
                  class="rounded-5px hover:bg-muted focus:bg-muted focus:text-foreground aria-[valuetext=Empty]:text-muted-foreground focus-visible:ring-0! focus-visible:ring-offset-0! px-1 py-1"
                >
                  {value}
                </DateRangeField.Segment>
              {/if}
            </div>
          {/each}
        {/snippet}
      </DateRangeField.Input>
      {#if type === "start"}
        <div aria-hidden="true" class="text-muted-foreground px-1"></div>
      {/if}
    {/each}
  </div>
</DateRangeField.Root>
```

##### Heads up!

Before diving into this component, it's important to understand how dates/times work in Bits UI. Please read the [Dates](/docs/dates) documentation to learn more!

## Overview

The `DateRangeField` component combines two [Date Field](/docs/components/date-field) components to create a date range field. Check out the [Date Field](/docs/components/date-field) component documentation for information on how to customize this component.

## Structure

```svelte
<script lang="ts">
 import { DateRangeField } from "$lib";
</script>
<DateRangeField.Root>
 <DateRangeField.Label>Check-in date</DateRangeField.Label>
 {#each ["start", "end"] as const as type}
  <DateRangeField.Input {type}>
   {#snippet children({ segments })}
    {#each segments as { part, value }}
     <DateRangeField.Segment {part}>
      {value}
     </DateRangeField.Segment>
    {/each}
   {/snippet}
  </DateRangeField.Input>
 {/each}
</DateRangeField.Root>
```

## Managing Placeholder State

This section covers how to manage the `placeholder` state of the component.

### Two-Way Binding

Use `bind:placeholder` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { DateRangeField } from "bits-ui";
 import { CalendarDateTime } from "@internationalized/date";
 let myPlaceholder = $state(new CalendarDateTime(2024, 8, 3, 12, 30));
</script>
<DateRangeField.Root bind:placeholder={myPlaceholder}>
</DateRangeField.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { DateRangeField } from "bits-ui";
 import { CalendarDateTime } from "@internationalized/date";
 let myPlaceholder = $state(new CalendarDateTime(2024, 8, 3, 12, 30));
 function getPlaceholder() {
  return myPlaceholder;
 }
 function setPlaceholder(newPlaceholder: CalendarDateTime) {
  myPlaceholder = newPlaceholder;
 }
</script>
<DateRangeField.Root bind:placeholder={getPlaceholder, setPlaceholder}>
</DateRangeField.Root>
```

## Managing Value State

This section covers how to manage the `value` state of the component.

### Two-Way Binding

Use `bind:value` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { DateRangeField, type DateRange } from "bits-ui";
 import { CalendarDateTime } from "@internationalized/date";
 let myValue = $state<DateRange>({
  start: new CalendarDateTime(2024, 8, 3, 12, 30),
  end: new CalendarDateTime(2024, 8, 4, 12, 30),
 });
</script>
<button
 onclick={() => {
  value = {
   start: value.start.add({ days: 1 }),
   end: value.end.add({ days: 1 }),
  };
 }}
>
 Add 1 day
</button>
<DateRangeField.Root bind:value={myValue}>
</DateRangeField.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { DateRangeField } from "bits-ui";
 let myValue = $state<DateRange>({
  start: undefined,
  end: undefined,
 });
 function getValue() {
  return myValue;
 }
 function setValue(newValue: DateRange) {
  myValue = newValue;
 }
</script>
<DateRangeField.Root bind:value={getValue, setValue}>
</DateRangeField.Root>
```

## API Reference

### DateRangeField.Root

The root date field component.

| Property                                                                                      | Type                                                                                                                                                                                                                                                                                                                                                     | Description                                                                                                                                                                                                                                                                                           |
| -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` $bindable | `DateRange`- { start: DateValue; end: DateValue }                                                                                                                             | The selected date range.`Default:  undefined`                                                                                                                                                                                                                        |
| `onValueChange`                                             | `function`- (value: DateRange) => void                                                                                                                                        | A function that is called when the selected date changes.`Default:  undefined`                                                                                                                                                                                       |
| `placeholder` $bindable                        | `DateValue`- import type { CalendarDate, CalendarDateTime, ZonedDateTime } from "@internationalized/date"; type DateValue = CalendarDate \| CalendarDateTime \| ZonedDateTime | The placeholder date, which is used to determine what date to start the segments from when no value exists.`Default:  undefined`                                                                                                                                     |
| `onPlaceholderChange`                                       | `function`- (value: DateValue) => void                                                                                                                                        | A function that is called when the placeholder date changes.`Default:  undefined`                                                                                                                                                                                    |
| `errorMessageId`                                            | `string`                                                                                                                                                                                                                                                                                                      | The `id` of the element which contains the error messages for the date field when the date is invalid.`Default:  undefined`                                                                                                                                          |
| `validate`                                                  | `function`- (value: DateValue) => boolean                                                                                                                                     | A function that returns whether or not a date is unavailable.`Default:  undefined`                                                                                                                                                                                   |
| `onInvalid`                                                 | `function`- (value: DateValue) => void                                                                                                                                        | A callback fired when the date field's value is invalid.`Default:  undefined`                                                                                                                                                                                        |
| `minValue`                                                  | `DateValue`- import type { CalendarDate, CalendarDateTime, ZonedDateTime } from "@internationalized/date"; type DateValue = CalendarDate \| CalendarDateTime \| ZonedDateTime | The minimum valid date that can be entered.`Default:  undefined`                                                                                                                                                                                                     |
| `maxValue`                                                  | `DateValue`- import type { CalendarDate, CalendarDateTime, ZonedDateTime } from "@internationalized/date"; type DateValue = CalendarDate \| CalendarDateTime \| ZonedDateTime | The maximum valid date that can be entered.`Default:  undefined`                                                                                                                                                                                                     |
| `granularity`                                               | `enum`- 'day' \| 'hour' \| 'minute' \| 'second'                                                                                                                               | The granularity to use for formatting the field. Defaults to `'day'` if a `CalendarDate` is provided, otherwise defaults to `'minute'`. The field will render segments for each part of the date up to and including the specified granularity.`Default:  undefined` |
| `hideTimeZone`                                              | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not to hide the time zone segment of the field.`Default: false`                                                                                                                                                                                              |
| `hourCycle`                                                 | `enum`- '12' \| '24'                                                                                                                                                          | The hour cycle to use for formatting times. Defaults to the locale preference`Default:  undefined`                                                                                                                                                                   |
| `locale`                                                    | `string`                                                                                                                                                                                                                                                                                                      | The locale to use for formatting dates.`Default: 'en-US'`                                                                                                                                                                                                               |
| `disabled`                                                  | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not the accordion is disabled.`Default: false`                                                                                                                                                                                                               |
| `readonly`                                                  | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not the field is readonly.`Default: false`                                                                                                                                                                                                                   |
| `readonlySegments`                                          | `EditableSegmentPart[]`- "day" \| "month" \| "year" \| "hour" \| "minute" \| "second" \| "dayPeriod"                                                                          | An array of segments that should be readonly, which prevent user input on them.`Default:  undefined`                                                                                                                                                                 |
| `required`                                                  | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not the date field is required.`Default: false`                                                                                                                                                                                                              |
| `onStartValueChange`                                        | `function`- (value: DateValue) => void                                                                                                                                        | A function that is called when the start date changes.`Default:  undefined`                                                                                                                                                                                          |
| `onEndValueChange`                                          | `function`- (value: DateValue) => void                                                                                                                                        | A function that is called when the end date changes.`Default:  undefined`                                                                                                                                                                                            |
| `ref` $bindable                                | `HTMLDivElement`                                                                                                                                                                                                                                                                                              | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                              |
| `children`                                                  | `Snippet`                                                                                                                                                                                                                                                                                                     | The children content to render.`Default:  undefined`                                                                                                                                                                                                                 |
| `child`                                                     | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };                                                                                                          | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                       | | Data Attribute                                             | Value         | Description                                                                                     |
| --------------------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-date-range-field-root` | `''` | Present on the root element. |

### DateRangeField.Input

The container for the segments of the date field.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` required | `enum`- 'start' \| 'end'                                             | The type of field to render (start or end).`Default:  undefined`                                                                                                               |
| `name`                                                    | `string`                                                                                                                                                                                             | The name of the date field used for form submission. If provided, a hidden input element will be rendered alongside the date field.`Default:  undefined`                       |
| `ref` $bindable                              | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`- Snippet                                                   | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                               | Value         | Description                                                                                |
| ------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `data-invalid` | `''` | Present on the element when the field is invalid.                   |
| `data-disabled`                                     | `''` | Present on the element when the field is disabled.                  |
| `data-date-field-input`                             | `''` | Present on the element. |

### DateRangeField.Segment

A segment of the date field.

| Property                                                                                    | Type                                                                                                                                                                                                                                                                                                 | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `part` required | `SegmentPart`- "month" \| "day" \| "year" \| "hour" \| "minute" \| "second" \| "dayPeriod" \| "timeZoneName" \| "literal" | The part of the date to render.`Default:  undefined`                                                                                                                           |
| `ref` $bindable                              | `HTMLSpanElement`                                                                                                                                                                                                                                         | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                                                                                 | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };                                                      | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                               | Value                                                                                                                                                                         | Description                                                                                |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `data-invalid` | `''`                                                                                                                                                                 | Present on the element when the field is invalid                    |
| `data-disabled`                                     | `''`                                                                                                                                                                 | Present on the element when the field is disabled                   |
| `data-segment`                                      | `enum`- '' | The type of segment the element represents.                         |
| `data-date-field-segment`                           | `''`                                                                                                                                                                 | Present on the element. |

### DateRangeField.Label

The label for the date field.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLSpanElement`                                                                                                                                                                                    | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                               | Value         | Description                                                                                |
| ------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `data-invalid` | `''` | Present on the element when the field is invalid                    |
| `data-date-field-label`                             | `''` | Present on the element. |

----------------------------------------------------

# Date Range Picker Documentation

Facilitates the selection of date ranges through an input and calendar-based interface.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { DateRangePicker } from "bits-ui";
  import CalendarBlank from "phosphor-svelte/lib/CalendarBlank";
  import CaretLeft from "phosphor-svelte/lib/CaretLeft";
  import CaretRight from "phosphor-svelte/lib/CaretRight";
</script>
<DateRangePicker.Root
  weekdayFormat="short"
  fixedWeeks={true}
  class="flex w-full max-w-[340px] flex-col gap-1.5"
>
  <DateRangePicker.Label class="block select-none text-sm font-medium"
    >Rental Days</DateRangePicker.Label
  >
  <div
    class="h-input rounded-input border-border-input bg-background text-foreground focus-within:border-border-input-hover focus-within:shadow-date-field-focus hover:border-border-input-hover flex w-full select-none items-center border px-2 py-3 text-sm tracking-[0.01em]"
  >
    {#each ["start", "end"] as const as type}
      <DateRangePicker.Input {type}>
        {#snippet children({ segments })}
          {#each segments as { part, value }}
            <div class="inline-block select-none">
              {#if part === "literal"}
                <DateRangePicker.Segment
                  {part}
                  class="text-muted-foreground p-1"
                >
                  {value}
                </DateRangePicker.Segment>
              {:else}
                <DateRangePicker.Segment
                  {part}
                  class="rounded-5px hover:bg-muted focus:bg-muted focus:text-foreground aria-[valuetext=Empty]:text-muted-foreground focus-visible:ring-0! focus-visible:ring-offset-0! px-1 py-1"
                >
                  {value}
                </DateRangePicker.Segment>
              {/if}
            </div>
          {/each}
        {/snippet}
      </DateRangePicker.Input>
      {#if type === "start"}
        <div aria-hidden="true" class="text-muted-foreground px-1"></div>
      {/if}
    {/each}
    <DateRangePicker.Trigger
      class="text-foreground/60 hover:bg-muted active:bg-dark-10 ml-auto inline-flex size-8 items-center justify-center rounded-[5px] transition-all"
    >
      <CalendarBlank class="size-6" />
    </DateRangePicker.Trigger>
  </div>
  <DateRangePicker.Content sideOffset={6} class="z-50">
    <DateRangePicker.Calendar
      class="rounded-15px border-dark-10 bg-background-alt shadow-popover mt-6 border p-[22px]"
    >
      {#snippet children({ months, weekdays })}
        <DateRangePicker.Header class="flex items-center justify-between">
          <DateRangePicker.PrevButton
            class="rounded-9px bg-background-alt hover:bg-muted inline-flex size-10 items-center justify-center transition-all active:scale-[0.98]"
          >
            <CaretLeft class="size-6" />
          </DateRangePicker.PrevButton>
          <DateRangePicker.Heading class="text-[15px] font-medium" />
          <DateRangePicker.NextButton
            class="rounded-9px bg-background-alt hover:bg-muted inline-flex size-10 items-center justify-center transition-all active:scale-[0.98]"
          >
            <CaretRight class="size-6" />
          </DateRangePicker.NextButton>
        </DateRangePicker.Header>
        <div
          class="flex flex-col space-y-4 pt-4 sm:flex-row sm:space-x-4 sm:space-y-0"
        >
          {#each months as month}
            <DateRangePicker.Grid
              class="w-full border-collapse select-none space-y-1"
            >
              <DateRangePicker.GridHead>
                <DateRangePicker.GridRow
                  class="mb-1 flex w-full justify-between"
                >
                  {#each weekdays as day}
                    <DateRangePicker.HeadCell
                      class="text-muted-foreground font-normal! w-10 rounded-md text-xs"
                    >
                      <div>{day.slice(0, 2)}</div>
                    </DateRangePicker.HeadCell>
                  {/each}
                </DateRangePicker.GridRow>
              </DateRangePicker.GridHead>
              <DateRangePicker.GridBody>
                {#each month.weeks as weekDates}
                  <DateRangePicker.GridRow class="flex w-full">
                    {#each weekDates as date}
                      <DateRangePicker.Cell
                        {date}
                        month={month.value}
                        class="p-0! relative m-0 size-10 overflow-visible text-center text-sm focus-within:relative focus-within:z-20"
                      >
                        <DateRangePicker.Day
                          class={"rounded-9px text-foreground hover:border-foreground focus-visible:ring-foreground! data-selection-end:rounded-9px data-selection-start:rounded-9px data-highlighted:bg-muted data-selected:bg-muted data-selection-end:bg-foreground data-selection-start:bg-foreground data-disabled:text-foreground/30 data-selected:text-foreground data-selection-end:text-background data-selection-start:text-background data-unavailable:text-muted-foreground data-selected:[&:not([data-selection-start])]:[&:not([data-selection-end])]:focus-visible:border-foreground data-disabled:pointer-events-none data-outside-month:pointer-events-none  data-highlighted:rounded-none data-selected:font-medium data-selection-end:font-medium data-selection-start:font-medium data-unavailable:line-through data-selection-start:focus-visible:ring-2 data-selection-start:focus-visible:ring-offset-2! data-selected:[&:not([data-selection-start])]:[&:not([data-selection-end])]:rounded-none data-selected:[&:not([data-selection-start])]:[&:not([data-selection-end])]:focus-visible:ring-0! data-selected:[&:not([data-selection-start])]:[&:not([data-selection-end])]:focus-visible:ring-offset-0! group relative inline-flex size-10 items-center justify-center overflow-visible whitespace-nowrap border border-transparent bg-transparent p-0 text-sm font-normal transition-all"}
                        >
                          <div
                            class="bg-foreground group-data-selected:bg-background group-data-today:block absolute top-[5px] hidden size-1 rounded-full transition-all"
                          ></div>
                          {date.day}
                        </DateRangePicker.Day>
                      </DateRangePicker.Cell>
                    {/each}
                  </DateRangePicker.GridRow>
                {/each}
              </DateRangePicker.GridBody>
            </DateRangePicker.Grid>
          {/each}
        </div>
      {/snippet}
    </DateRangePicker.Calendar>
  </DateRangePicker.Content>
</DateRangePicker.Root>
```

##### Heads up!

Before diving into this component, it's important to understand how dates/times work in Bits UI. Please read the [Dates](/docs/dates) documentation to learn more!

## Structure

```svelte
<script lang="ts">
 import { DateRangePicker } from "bits-ui";
</script>
<DateRangePicker.Root>
 <DateRangePicker.Label />
 {#each ["start", "end"] as const as type}
  <DateRangePicker.Input {type}>
   {#snippet children({ segments })}
    {#each segments as { part, value }}
     <DateRangePicker.Segment {part}>
      {value}
     </DateRangePicker.Segment>
    {/each}
   {/snippet}
  </DateRangePicker.Input>
 {/each}
 <DateRangePicker.Trigger />
 <DateRangePicker.Content>
  <DateRangePicker.Calendar>
   {#snippet children({ months, weekdays })}
    <DateRangePicker.Header>
     <DateRangePicker.PrevButton />
     <DateRangePicker.Heading />
     <DateRangePicker.NextButton />
    </DateRangePicker.Header>
    {#each months as month}
     <DateRangePicker.Grid>
      <DateRangePicker.GridHead>
       <DateRangePicker.GridRow>
        {#each weekdays as day}
         <DateRangePicker.HeadCell>
          {day}
         </DateRangePicker.HeadCell>
        {/each}
       </DateRangePicker.GridRow>
      </DateRangePicker.GridHead>
      <DateRangePicker.GridBody>
       {#each month.weeks as weekDates}
        <DateRangePicker.GridRow>
         {#each weekDates as date}
          <DateRangePicker.Cell {date} month={month.value}>
           <DateRangePicker.Day>
            {date.day}
           </DateRangePicker.Day>
          </DateRangePicker.Cell>
         {/each}
        </DateRangePicker.GridRow>
       {/each}
      </DateRangePicker.GridBody>
     </DateRangePicker.Grid>
    {/each}
   {/snippet}
  </DateRangePicker.Calendar>
 </DateRangePicker.Content>
</DateRangePicker.Root>
```

## Managing Placeholder State

This section covers how to manage the `placeholder` state of the component.

### Two-Way Binding

Use `bind:placeholder` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { DateRangePicker } from "bits-ui";
 import { CalendarDateTime } from "@internationalized/date";
 let myPlaceholder = $state(new CalendarDateTime(2024, 8, 3, 12, 30));
</script>
<DateRangePicker.Root bind:placeholder={myPlaceholder}>
</DateRangePicker.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { DateRangePicker } from "bits-ui";
 import type { DateValue } from "@internationalized/date";
 let myPlaceholder = $state<DateValue>();
 function getPlaceholder() {
  return myPlaceholder;
 }
 function setPlaceholder(newPlaceholder: DateValue) {
  myPlaceholder = newPlaceholder;
 }
</script>
<DateRangePicker.Root bind:placeholder={getPlaceholder, setPlaceholder}>
</DateRangePicker.Root>
```

## Managing Value State

This section covers how to manage the `value` state of the component.

### Two-Way Binding

Use `bind:value` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { DateRangePicker } from "bits-ui";
 import { CalendarDateTime } from "@internationalized/date";
 let myValue = $state({
  start: new CalendarDateTime(2024, 8, 3, 12, 30),
  end: new CalendarDateTime(2024, 8, 4, 12, 30),
 });
</script>
<button
 onclick={() => {
  value = {
   start: value.start.add({ days: 1 }),
   end: value.end.add({ days: 1 }),
  };
 }}
>
 Add 1 day
</button>
<DateRangePicker.Root bind:value={myValue}>
</DateRangePicker.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { DateRangePicker, type DateRange } from "bits-ui";
 let myValue = $state<DateRange>();
 function getValue() {
  return myValue;
 }
 function setValue(newValue: DateRange) {
  myValue = newValue;
 }
</script>
<DateRangePicker.Root bind:value={getValue, setValue}>
</DateRangePicker.Root>
```

## Managing Open State

This section covers how to manage the `open` state of the component.

### Two-Way Binding

Use `bind:open` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { DateRangePicker } from "bits-ui";
 let isOpen = $state(false);
</script>
<button onclick={() => (isOpen = true)}>Open DateRangePicker</button>
<DateRangePicker.Root bind:open={isOpen}>
</DateRangePicker.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { DateRangePicker } from "bits-ui";
 let myOpen = $state(false);
 function getOpen() {
  return myOpen;
 }
 function setOpen(newOpen: boolean) {
  myOpen = newOpen;
 }
</script>
<DateRangePicker.Root bind:open={getOpen, setOpen}>
</DateRangePicker.Root>
```

## Customization

The `DateRangePicker` component is made up of three other Bits UI components: [Date Range Field](/docs/components/date-range-field), [Range Calendar](/docs/components/range-calendar), and [Popover](/docs/components/popover).

You can check out the documentation for each of these components to learn more about their customization options, each of which can be used to customize the `DateRangePicker` component.

## API Reference

### DateRangePicker.Root

The root date picker component.

| Property                                                                                      | Type                                                                                                                                                                                                                                                                                                                                                     | Description                                                                                                                                                                                                                                                                                           |
| -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` $bindable | `DateRange`- { start: DateValue; end: DateValue }                                                                                                                             | The selected date range.`Default:  undefined`                                                                                                                                                                                                                        |
| `onValueChange`                                             | `function`- (value: DateRange) => void                                                                                                                                        | A function that is called when the selected date changes.`Default:  undefined`                                                                                                                                                                                       |
| `placeholder` $bindable                        | `DateValue`- import type { CalendarDate, CalendarDateTime, ZonedDateTime } from "@internationalized/date"; type DateValue = CalendarDate \| CalendarDateTime \| ZonedDateTime | The placeholder date, which is used to determine what date to start the segments from when no value exists.`Default:  undefined`                                                                                                                                     |
| `onPlaceholderChange`                                       | `function`- (value: DateValue) => void                                                                                                                                        | A function that is called when the placeholder date changes.`Default:  undefined`                                                                                                                                                                                    |
| `readonlySegments`                                          | `EditableSegmentPart[]`- "day" \| "month" \| "year" \| "hour" \| "minute" \| "second" \| "dayPeriod"                                                                          | An array of segments that should be readonly, which prevent user input on them.`Default:  undefined`                                                                                                                                                                 |
| `isDateUnavailable`                                         | `function`- (date: DateValue) => boolean                                                                                                                                      | A function that returns whether or not a date is unavailable.`Default:  undefined`                                                                                                                                                                                   |
| `minValue`                                                  | `DateValue`- import type { CalendarDate, CalendarDateTime, ZonedDateTime } from "@internationalized/date"; type DateValue = CalendarDate \| CalendarDateTime \| ZonedDateTime | The minimum valid date that can be entered.`Default:  undefined`                                                                                                                                                                                                     |
| `maxValue`                                                  | `DateValue`- import type { CalendarDate, CalendarDateTime, ZonedDateTime } from "@internationalized/date"; type DateValue = CalendarDate \| CalendarDateTime \| ZonedDateTime | The maximum valid date that can be entered.`Default:  undefined`                                                                                                                                                                                                     |
| `validate`                                                  | `function`- (value: DateValue) => boolean                                                                                                                                     | A function that returns whether or not a date is unavailable.`Default:  undefined`                                                                                                                                                                                   |
| `onInvalid`                                                 | `function`- (value: DateValue) => void                                                                                                                                        | A callback fired when the date field's value is invalid.`Default:  undefined`                                                                                                                                                                                        |
| `granularity`                                               | `enum`- 'day' \| 'hour' \| 'minute' \| 'second'                                                                                                                               | The granularity to use for formatting the field. Defaults to `'day'` if a `CalendarDate` is provided, otherwise defaults to `'minute'`. The field will render segments for each part of the date up to and including the specified granularity.`Default:  undefined` |
| `hideTimeZone`                                              | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not to hide the time zone segment of the field.`Default: false`                                                                                                                                                                                              |
| `errorMessageId`                                            | `string`                                                                                                                                                                                                                                                                                                      | The `id` of the element which contains the error messages for the date field when the date is invalid.`Default:  undefined`                                                                                                                                          |
| `hourCycle`                                                 | `enum`- '12' \| '24'                                                                                                                                                          | The hour cycle to use for formatting times. Defaults to the locale preference`Default:  undefined`                                                                                                                                                                   |
| `locale`                                                    | `string`                                                                                                                                                                                                                                                                                                      | The locale to use for formatting dates.`Default: 'en-US'`                                                                                                                                                                                                               |
| `disabled`                                                  | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not the accordion is disabled.`Default: false`                                                                                                                                                                                                               |
| `readonly`                                                  | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not the field is readonly.`Default: false`                                                                                                                                                                                                                   |
| `required`                                                  | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not the date field is required.`Default: false`                                                                                                                                                                                                              |
| `closeOnRangeSelect`                                        | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not to close the popover when a date range is selected.`Default: true`                                                                                                                                                                                       |
| `disableDaysOutsideMonth`                                   | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not to disable days outside the current month.`Default: false`                                                                                                                                                                                               |
| `pagedNavigation`                                           | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not to use paged navigation for the calendar. Paged navigation causes the previous and next buttons to navigate by the number of months displayed at once, rather than by one month.`Default: false`                                                         |
| `preventDeselect`                                           | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not to prevent the user from deselecting a date without selecting another date first.`Default: false`                                                                                                                                                        |
| `weekdayFormat`                                             | `enum`- 'narrow' \| 'short' \| 'long'                                                                                                                                         | The format to use for the weekday strings provided via the `weekdays` slot prop.`Default: 'narrow'`                                                                                                                                                                     |
| `weekStartsOn`                                              | `number`                                                                                                                                                                                                                                                                                                      | The day of the week to start the calendar on. 0 is Sunday, 1 is Monday, etc.`Default: 0`                                                                                                                                                                                |
| `calendarLabel`                                             | `string`                                                                                                                                                                                                                                                                                                      | The accessible label for the calendar.`Default:  undefined`                                                                                                                                                                                                          |
| `fixedWeeks`                                                | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not to always display 6 weeks in the calendar.`Default: false`                                                                                                                                                                                               |
| `isDateDisabled`                                            | `function`- (date: DateValue) => boolean                                                                                                                                      | A function that returns whether or not a date is disabled.`Default:  undefined`                                                                                                                                                                                      |
| `numberOfMonths`                                            | `number`                                                                                                                                                                                                                                                                                                      | The number of months to display at once.`Default: 1`                                                                                                                                                                                                                    |
| `open` $bindable                               | `boolean`                                                                                                                                                                                                                                                                                                     | The open state of the popover content.`Default: false`                                                                                                                                                                                                                  |
| `onOpenChange`                                              | `function`- (open: boolean) => void                                                                                                                                           | A callback that fires when the open state changes.`Default:  undefined`                                                                                                                                                                                              |
| `onEndValueChange`                                          | `function`- (value: DateValue) => void                                                                                                                                        | A function that is called when the end date changes.`Default:  undefined`                                                                                                                                                                                            |
| `onStartValueChange`                                        | `function`- (value: DateValue) => void                                                                                                                                        | A function that is called when the start date changes.`Default:  undefined`                                                                                                                                                                                          |
| `ref` $bindable                                | `HTMLDivElement`                                                                                                                                                                                                                                                                                              | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                              |
| `children`                                                  | `Snippet`                                                                                                                                                                                                                                                                                                     | The children content to render.`Default:  undefined`                                                                                                                                                                                                                 |
| `child`                                                     | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };                                                                                                          | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                       | | Data Attribute                               | Value         | Description                                                                                     |
| ------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-invalid` | `''` | Present on the root element when the calendar is invalid.                |
| `data-disabled`                                     | `''` | Present on the root element when the calendar is disabled.               |
| `data-readonly`                                     | `''` | Present on the root element when the calendar is readonly.               |
| `data-calendar-root`                                | `''` | Present on the root element. |

### DateRangePicker.Label

The label for the date field.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLSpanElement`                                                                                                                                                                                    | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                               | Value         | Description                                                                                |
| ------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `data-invalid` | `''` | Present on the element when the field is invalid                    |
| `data-date-field-label`                             | `''` | Present on the element. |

### DateRangePicker.Input

The field input component which contains the segments of the date field.

| Property                                                              | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | `string`                                                                                                                                                                                             | The name of the input field used for form submission. If provided a hidden input will be rendered alongside the field.`Default:  undefined`                                    |
| `type` required        | `enum`- 'start' \| 'end'                                             | The type of field to render (start or end).`Default:  undefined`                                                                                                               |
| `ref` $bindable        | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                          | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                             | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                               | Value         | Description                                                                                |
| ------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `data-invalid` | `''` | Present on the element when the field is invalid.                   |
| `data-disabled`                                     | `''` | Present on the element when the field is disabled.                  |
| `data-date-field-input`                             | `''` | Present on the element. |

### DateRangePicker.Segment

A segment of the date field.

| Property                                                                                    | Type                                                                                                                                                                                                                                                                                                 | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `part` required | `SegmentPart`- "month" \| "day" \| "year" \| "hour" \| "minute" \| "second" \| "dayPeriod" \| "timeZoneName" \| "literal" | The part of the date to render.`Default:  undefined`                                                                                                                           |
| `ref` $bindable                              | `HTMLSpanElement`                                                                                                                                                                                                                                         | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                                                                                 | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };                                                      | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                               | Value                                                                                                                                                                         | Description                                                                                |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `data-invalid` | `''`                                                                                                                                                                 | Present on the element when the field is invalid                    |
| `data-disabled`                                     | `''`                                                                                                                                                                 | Present on the element when the field is disabled                   |
| `data-segment`                                      | `enum`- '' | The type of segment the element represents.                         |
| `data-date-field-segment`                           | `''`                                                                                                                                                                 | Present on the element. |

### DateRangePicker.Trigger

A component which toggles the opening and closing of the popover on press.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                        |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | Whether the popover is open or closed.                                      |
| `data-popover-trigger`                            | `''`                                                                                                                                                                                 | Present on the trigger element. |

### DateRangePicker.Content

The contents of the popover which are displayed when the popover is open.

| Property                                                              | Type                                                                                                                                                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `side` | `enum`- 'top' \| 'bottom' \| 'left' \| 'right'                                     | The preferred side of the anchor to render the floating element against when open. Will be reversed when collisions occur.`Default: bottom`                                                                                                                                                                                                                                                                                        |
| `sideOffset`                        | `number`                                                                                                                                                                                                           | The distance in pixels from the anchor to the floating element.`Default: 0`                                                                                                                                                                                                                                                                                                                                                        |
| `align`                             | `enum`- 'start' \| 'center' \| 'end'                                               | The preferred alignment of the anchor to render the floating element against when open. This may change when collisions occur.`Default: start`                                                                                                                                                                                                                                                                                     |
| `alignOffset`                       | `number`                                                                                                                                                                                                           | The distance in pixels from the anchor to the floating element.`Default: 0`                                                                                                                                                                                                                                                                                                                                                        |
| `arrowPadding`                      | `number`                                                                                                                                                                                                           | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0`                                                                                                                                                                                                                                                                                                  |
| `avoidCollisions`                   | `boolean`                                                                                                                                                                                                          | When `true`, overrides the `side` and `align` options to prevent collisions with the boundary edges.`Default: true`                                                                                                                                                                                                                                                                                                                |
| `collisionBoundary`                 | `union`- Element \| null                                                           | A boundary element or array of elements to check for collisions against.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                   |
| `collisionPadding`                  | `union`- number \| Partial\&lt;Record\&lt;Side, number\&gt;\&gt;                   | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0`                                                                                                                                                                                                                                                                                                  |
| `sticky`                            | `enum`- 'partial' \| 'always'                                                      | The sticky behavior on the align axis. `'partial'` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst `'always'` will keep the content in the boundary regardless.`Default: partial`                                                                                                                                                                                        |
| `hideWhenDetached`                  | `boolean`                                                                                                                                                                                                          | When `true`, hides the content when it is detached from the DOM. This is useful for when you want to hide the content when the user scrolls away.`Default: true`                                                                                                                                                                                                                                                                   |
| `updatePositionStrategy`            | `enum`- 'optimized' \| 'always'                                                    | The strategy to use when updating the position of the content. When `'optimized'` the content will only be repositioned when the trigger is in the viewport. When `'always'` the content will be repositioned whenever the position changes.`Default: optimized`                                                                                                                                                                   |
| `strategy`                          | `enum`- 'fixed' \| 'absolute'                                                      | The positioning strategy to use for the floating element. When `'fixed'` the element will be positioned relative to the viewport. When `'absolute'` the element will be positioned relative to the nearest positioned ancestor.`Default: fixed`                                                                                                                                                                                    |
| `preventScroll`                     | `boolean`                                                                                                                                                                                                          | When `true`, prevents the body from scrolling when the content is open. This is useful when you want to use the content as a modal.`Default: false`                                                                                                                                                                                                                                                                                |
| `customAnchor`                      | `union`- string \| HTMLElement \| Measurable \| null                               | Use an element other than the trigger to anchor the content to. If provided, the content will be anchored to the provided element instead of the trigger.`Default: null`                                                                                                                                                                                                                                                           |
| `onInteractOutside`                 | `function`- (event: PointerEvent) => void                                          | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default:  undefined`                                                                                                                                                                                                        |
| `onFocusOutside`                    | `function`- (event: FocusEvent) => void                                            | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default:  undefined`                                                                                                                                                                                                                                                  |
| `interactOutsideBehavior`           | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close`  |
| `onEscapeKeydown`                   | `function`- (event: KeyboardEvent) => void                                         | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default:  undefined`                                                                                                                                                                                                                    |
| `escapeKeydownBehavior`             | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` |
| `onOpenAutoFocus`                   | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is opened. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `onCloseAutoFocus`                  | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is closed. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `trapFocus`                         | `boolean`                                                                                                                                                                                                          | Whether or not to trap the focus within the content when open.`Default: true`                                                                                                                                                                                                                                                                                                                                                      |
| `preventOverflowTextSelection`      | `boolean`                                                                                                                                                                                                          | When `true`, prevents the text selection from overflowing the bounds of the element.`Default: true`                                                                                                                                                                                                                                                                                                                                |
| `forceMount`                        | `boolean`                                                                                                                                                                                                          | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                                                                                                                                                                                                                                                                 |
| `dir`                               | `enum`- 'ltr' \| 'rtl'                                                             | The reading direction of the app.`Default: 'ltr'`                                                                                                                                                                                                                                                                                                                                                                                  |
| `ref` $bindable        | `HTMLDivElement`                                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                                                                                                                                                                         |
| `children`                          | `Snippet`                                                                                                                                                                                                          | The children content to render.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                                                            |
| `child`                             | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };               | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                                                                                                                                                                  | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                        |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | Whether the popover is open or closed.                                      |
| `data-popover-content`                            | `''`                                                                                                                                                                                 | Present on the content element. |

| CSS Variable                                                            | Description                                                                                                   |
| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--bits-popover-content-transform-origin` | The transform origin of the popover content element.                                   |
| `--bits-popover-content-available-width`                                       | The available width of the popover content element.                                    |
| `--bits-popover-content-available-height`                                      | The available height of the popover content element.                                   |
| `--bits-popover-anchor-width`                                                  | The width of the popover trigger element.                                              |
| `--bits-popover-anchor-height`                                                 | The height of the popover trigger element. |

### DateRangePicker.Calendar

The calendar component containing the grids of dates.

| Data Attribute                               | Value         | Description                                                                                     |
| ------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-invalid` | `''` | Present on the root element when the calendar is invalid.                |
| `data-disabled`                                     | `''` | Present on the root element when the calendar is disabled.               |
| `data-readonly`                                     | `''` | Present on the root element when the calendar is readonly.               |
| `data-calendar-root`                                | `''` | Present on the root element. |

### DateRangePicker.Header

The header of the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLElement`                                                                                                                                                                                        | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                       |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the header element when the calendar is disabled.               |
| `data-readonly`                                      | `''` | Present on the header element when the calendar is readonly.               |
| `data-calendar-header`                               | `''` | Present on the header element. |

### DateRangePicker.PrevButton

The previous button of the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                             |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the prev button element when the calendar or this button is disabled. |
| `data-calendar-prev-button`                          | `''` | Present on the prev button element.  |

### DateRangePicker.Heading

The heading of the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                        |
| -------------------------------------------------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the heading element when the calendar is disabled.               |
| `data-readonly`                                      | `''` | Present on the heading element when the calendar is readonly.               |
| `data-calendar-heading`                              | `''` | Present on the heading element. |

### DateRangePicker.NextButton

The next button of the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                             |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the next button element when the calendar or this button is disabled. |
| `data-calendar-next-button`                          | `''` | Present on the next button element.  |

### DateRangePicker.Grid

The grid of dates in the calendar, typically representing a month.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLTableElement`                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                     |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the grid element when the calendar is disabled.               |
| `data-readonly`                                      | `''` | Present on the grid element when the calendar is readonly.               |
| `data-calendar-grid`                                 | `''` | Present on the grid element. |

### DateRangePicker.GridRow

A row in the grid of dates in the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLTableRowElement`                                                                                                                                                                                | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                         |
| -------------------------------------------------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the grid row element when the calendar is disabled.               |
| `data-readonly`                                      | `''` | Present on the grid row element when the calendar is readonly.               |
| `data-calendar-grid-row`                             | `''` | Present on the grid row element. |

### DateRangePicker.GridHead

The head of the grid of dates in the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLTableSectionElement`                                                                                                                                                                            | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                          |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the grid head element when the calendar is disabled.               |
| `data-readonly`                                      | `''` | Present on the grid head element when the calendar is readonly.               |
| `data-calendar-grid-head`                            | `''` | Present on the grid head element. |

### DateRangePicker.HeadCell

A cell in the head of the grid of dates in the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLTableCellElement`                                                                                                                                                                               | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                          |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the head cell element when the calendar is disabled.               |
| `data-readonly`                                      | `''` | Present on the head cell element when the calendar is readonly.               |
| `data-calendar-head-cell`                            | `''` | Present on the head cell element. |

### DateRangePicker.GridBody

The body of the grid of dates in the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLTableSectionElement`                                                                                                                                                                            | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                          |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the grid element when the calendar is disabled.                    |
| `data-readonly`                                      | `''` | Present on the grid element when the calendar is readonly.                    |
| `data-calendar-grid-body`                            | `''` | Present on the grid body element. |

### DateRangePicker.Cell

A cell in the calendar grid.

| Property                                                              | Type                                                                                                                                                                                                                                                                                                                                                     | Description                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `date` | `DateValue`- import type { CalendarDate, CalendarDateTime, ZonedDateTime } from "@internationalized/date"; type DateValue = CalendarDate \| CalendarDateTime \| ZonedDateTime | The date for the cell.`Default:  undefined`                                                                                                                                    |
| `month`                             | `DateValue`- import type { CalendarDate, CalendarDateTime, ZonedDateTime } from "@internationalized/date"; type DateValue = CalendarDate \| CalendarDateTime \| ZonedDateTime | The current month the date is being displayed in.`Default:  undefined`                                                                                                         |
| `ref` $bindable        | `HTMLTableCellElement`                                                                                                                                                                                                                                                                                        | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                          | `Snippet`                                                                                                                                                                                                                                                                                                     | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                             | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };                                                                                                          | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                     |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present when the day is disabled.                                        |
| `data-unavailable`                                   | `''` | Present when the day is unavailable.                                     |
| `data-today`                                         | `''` | Present when the day is today.                                           |
| `data-outside-month`                                 | `''` | Present when the day is outside the current month.                       |
| `data-outside-visible-months`                        | `''` | Present when the day is outside the visible months.                      |
| `data-focused`                                       | `''` | Present when the day is focused.                                         |
| `data-selected`                                      | `''` | Present when the day is selected.                                        |
| `data-value`                                         | `''` | The date in the format "YYYY-MM-DD".                                     |
| `data-calendar-cell`                                 | `''` | Present on the cell element. |

### DateRangePicker.Day

A day in the calendar grid.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                    |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present when the day is disabled.                                       |
| `data-unavailable`                                   | `''` | Present when the day is unavailable.                                    |
| `data-today`                                         | `''` | Present when the day is today.                                          |
| `data-outside-month`                                 | `''` | Present when the day is outside the current month.                      |
| `data-outside-visible-months`                        | `''` | Present when the day is outside the visible months.                     |
| `data-focused`                                       | `''` | Present when the day is focused.                                        |
| `data-selected`                                      | `''` | Present when the day is selected.                                       |
| `data-value`                                         | `''` | The date in the format "YYYY-MM-DD".                                    |
| `data-calendar-day`                                  | `''` | Present on the day element. |

----------------------------------------------------

# Dialog Documentation

A modal window presenting content or seeking user input without navigating away from the current context.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { Dialog, Label, Separator } from "bits-ui";
  import LockKeyOpen from "phosphor-svelte/lib/LockKeyOpen";
  import X from "phosphor-svelte/lib/X";
</script>
<Dialog.Root>
  <Dialog.Trigger
    class="rounded-input bg-dark text-background
   shadow-mini hover:bg-dark/95 focus-visible:ring-foreground focus-visible:ring-offset-background focus-visible:outline-hidden
   inline-flex h-12 items-center justify-center whitespace-nowrap px-[21px] text-[15px] font-semibold transition-colors focus-visible:ring-2 focus-visible:ring-offset-2 active:scale-[0.98]"
  >
    New API key
  </Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay
      class="data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 fixed inset-0 z-50 bg-black/80"
    />
    <Dialog.Content
      class="rounded-card-lg bg-background shadow-popover data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 outline-hidden fixed left-[50%] top-[50%] z-50 w-full max-w-[calc(100%-2rem)] translate-x-[-50%] translate-y-[-50%] border p-5 sm:max-w-[490px] md:w-full"
    >
      <Dialog.Title
        class="flex w-full items-center justify-center text-lg font-semibold tracking-tight"
      >
        Create API key
      </Dialog.Title>
      <Separator.Root class="bg-muted -mx-5 mb-6 mt-5 block h-px" />
      <Dialog.Description class="text-foreground-alt text-sm">
        Create and manage API keys. You can create multiple keys to organize
        your applications.
      </Dialog.Description>
      <div class="flex flex-col items-start gap-1 pb-11 pt-7">
        <Label.Root for="apiKey" class="text-sm font-medium">API Key</Label.Root
        >
        <div class="relative w-full">
          <input
            id="apiKey"
            class="h-input rounded-card-sm border-border-input bg-background placeholder:text-foreground-alt/50 hover:border-dark-40 focus:ring-foreground focus:ring-offset-background focus:outline-hidden inline-flex w-full items-center border px-4 text-base focus:ring-2 focus:ring-offset-2 sm:text-sm"
            placeholder="secret_api_key"
            name="name"
          />
          <LockKeyOpen
            class="text-dark/30 absolute right-4 top-[14px] size-[22px]"
          />
        </div>
      </div>
      <div class="flex w-full justify-end">
        <Dialog.Close
          class="h-input rounded-input bg-dark text-background shadow-mini hover:bg-dark/95 focus-visible:ring-dark focus-visible:ring-offset-background focus-visible:outline-hidden inline-flex items-center justify-center px-[50px] text-[15px] font-semibold focus-visible:ring-2 focus-visible:ring-offset-2 active:scale-[0.98]"
        >
          Save
        </Dialog.Close>
      </div>
      <Dialog.Close
        class="focus-visible:ring-foreground focus-visible:ring-offset-background focus-visible:outline-hidden absolute right-5 top-5 rounded-md focus-visible:ring-2 focus-visible:ring-offset-2 active:scale-[0.98]"
      >
        <div>
          <X class="text-foreground size-5" />
          <span class="sr-only">Close</span>
        </div>
      </Dialog.Close>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog.Root>
```

## Overview

The Dialog component in Bits UI provides a flexible and accessible way to create modal dialogs in your Svelte applications. It follows a compound component pattern, allowing for fine-grained control over the dialog's structure and behavior while maintaining accessibility and ease of use.

## Key Features

- **Compound Component Structure**: Offers a set of sub-components that work together to create a fully-featured dialog.  
- **Accessibility**: Built with WAI-ARIA guidelines in mind, ensuring keyboard navigation and screen reader support.  
- **Customizable**: Each sub-component can be styled and configured independently.  
- **Portal Support**: Content can be rendered in a portal, ensuring proper stacking context.  
- **Managed Focus**: Automatically manages focus, with the option to take control if needed.  
- **Flexible State Management**: Supports both controlled and uncontrolled state, allowing for full control over the dialog's open state. ## Architecture

The Dialog component is composed of several sub-components, each with a specific role:

- **Root**: The main container component that manages the state of the dialog. Provides context for all child components.  
- **Trigger**: A button that toggles the dialog's open state.  
- **Portal**: Renders its children in a portal, outside the normal DOM hierarchy.  
- **Overlay**: A backdrop that sits behind the dialog content.  
- **Content**: The main container for the dialog's content.  
- **Title**: Renders the dialog's title.  
- **Description**: Renders a description or additional context for the dialog.  
- **Close**: A button that closes the dialog. ## Structure

Here's an overview of how the Dialog component is structured in code:

```svelte
<script lang="ts">
 import { Dialog } from "bits-ui";
</script>
<Dialog.Root>
 <Dialog.Trigger />
 <Dialog.Portal>
  <Dialog.Overlay />
  <Dialog.Content>
   <Dialog.Title />
   <Dialog.Description />
   <Dialog.Close />
  </Dialog.Content>
 </Dialog.Portal>
</Dialog.Root>
```

## Reusable Components

Bits UI provides a comprehensive set of Dialog components that serve as building blocks for creating customized, reusable Dialog implementations. This approach offers flexibility in design while maintaining consistency and accessibility across your application.

### Building a Reusable Dialog

The following example demonstrates how to create a versatile, reusable Dialog component using Bits UI building blocks. This implementation showcases the flexibility of the component API by combining props and snippets.

MyDialog.svelte

```svelte
<script lang="ts">
 import type { Snippet } from "svelte";
 import { Dialog, type WithoutChild } from "bits-ui";
 type Props = Dialog.RootProps & {
  buttonText: string;
  title: Snippet;
  description: Snippet;
  contentProps?: WithoutChild<Dialog.ContentProps>;
  // ...other component props if you wish to pass them
 };
 let {
  open = $bindable(false),
  children,
  buttonText,
  contentProps,
  title,
  description,
  ...restProps
 }: Props = $props();
</script>
<Dialog.Root bind:open {...restProps}>
 <Dialog.Trigger>
  {buttonText}
 </Dialog.Trigger>
 <Dialog.Portal>
  <Dialog.Overlay />
  <Dialog.Content {...contentProps}>
   <Dialog.Title>
    {@render title()}
   </Dialog.Title>
   <Dialog.Description>
    {@render description()}
   </Dialog.Description>
   {@render children?.()}
   <Dialog.Close>Close Dialog</Dialog.Close>
  </Dialog.Content>
 </Dialog.Portal>
</Dialog.Root>
```

#### Usage with Inline Snippets

```svelte
<script lang="ts">
 import MyDialog from "$lib/components/MyDialog.svelte";
</script>
<MyDialog buttonText="Open Dialog">
 {#snippet title()}
  Account settings
 {/snippet}
 {#snippet description()}
  Manage your account settings and preferences.
 {/snippet}
</MyDialog>
```

#### Usage with Separate Snippets

```svelte
<script lang="ts">
 import MyDialog from "$lib/components/MyDialog.svelte";
</script>
{#snippet title()}
 Account settings
{/snippet}
{#snippet description()}
 Manage your account settings and preferences.
{/snippet}
<MyDialog buttonText="Open Dialog" {title} {description}>
</MyDialog>
```

### Best Practices

- **Prop Flexibility**: Design your component to accept props for any nested components for maximum flexibility  
- **Styling Options**: Use tools like `clsx` to merge class overrides
- **Binding Props**: Use `bind:` and expose `$bindable` props to provide consumers with full control
- **Type Safety**: Use the exported types from Bits UI to type your component props ## Managing Open State

This section covers how to manage the `open` state of the component.

### Two-Way Binding

Use `bind:open` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { Dialog } from "bits-ui";
 let isOpen = $state(false);
</script>
<button onclick={() => (isOpen = true)}>Open Dialog</button>
<Dialog.Root bind:open={isOpen}>
</Dialog.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { Dialog } from "bits-ui";
 let myOpen = $state(false);
 function getOpen() {
  return myOpen;
 }
 function setOpen(newOpen: boolean) {
  myOpen = newOpen;
 }
</script>
<Dialog.Root bind:open={getOpen, setOpen}>
</Dialog.Root>
```

## Focus Management

Proper focus management is crucial for accessibility and user experience in modal dialogs. Bits UI's Dialog component provides several features to help you manage focus effectively.

### Focus Trap

By default, the Dialog implements a focus trap, adhering to the WAI-ARIA design pattern for modal dialogs. This ensures that keyboard focus remains within the Dialog while it's open, preventing users from interacting with the rest of the page.

#### Disabling the Focus Trap

While not recommended, you can disable the focus trap if absolutely necessary:

```svelte
<Dialog.Content trapFocus={false}>
</Dialog.Content>
```

##### Accessibility Warning

Disabling the focus trap may compromise accessibility. Only do this if you have a specific reason and implement an alternative focus management strategy.

### Open Focus

When a Dialog opens, focus is automatically set to the first focusable element within `Dialog.Content`. This ensures keyboard users can immediately interact with the Dialog contents.

#### Customizing Initial Focus

To specify which element receives focus when the Dialog opens, use the `onOpenAutoFocus` prop on `Dialog.Content`:

```svelte
<script lang="ts">
 import { Dialog } from "bits-ui";
 let nameInput = $state<HTMLInputElement>();
</script>
<Dialog.Root>
 <Dialog.Trigger>Open Dialog</Dialog.Trigger>
 <Dialog.Content
  onOpenAutoFocus={(e) => {
   e.preventDefault();
   nameInput?.focus();
  }}
 >
  <input type="text" bind:this={nameInput} />
 </Dialog.Content>
</Dialog.Root>
```

##### Important

Always ensure that *something* within the Dialog receives focus when it opens. This is crucial for maintaining keyboard navigation context and makes your users happy.

### Close Focus

When a Dialog closes, focus returns to the element that triggered its opening (typically the `Dialog.Trigger`).

#### Customizing Close Focus

To change which element receives focus when the Dialog closes, use the `onCloseAutoFocus` prop on `Dialog.Content`:

```svelte
<script lang="ts">
 import { Dialog } from "bits-ui";
 let nameInput = $state<HTMLInputElement>();
</script>
<input type="text" bind:this={nameInput} />
<Dialog.Root>
 <Dialog.Trigger>Open Dialog</Dialog.Trigger>
 <Dialog.Content
  onCloseAutoFocus={(e) => {
   e.preventDefault();
   nameInput?.focus();
  }}
 >
 </Dialog.Content>
</Dialog.Root>
```

### Best Practices

- Always maintain a clear focus management strategy for your Dialogs.  
- Ensure that focus is predictable and logical for keyboard users.  
- Test your focus management with keyboard navigation to verify its effectiveness. ## Advanced Behaviors

Bits UI's Dialog component offers several advanced features to customize its behavior and enhance user experience. This section covers scroll locking, escape key handling, and interaction outside the dialog.

### Scroll Lock

By default, when a Dialog opens, scrolling the body is disabled. This provides a more native-like experience, focusing user attention on the dialog content.

#### Customizing Scroll Behavior

To allow body scrolling while the dialog is open, use the `preventScroll` prop on `Dialog.Content`:

```svelte
<Dialog.Content preventScroll={false}>
</Dialog.Content>
```

##### Note

Enabling body scroll may affect user focus and accessibility. Use this option judiciously.

### Escape Key Handling

By default, pressing the `Escape` key closes an open Dialog. Bits UI provides two methods to customize this behavior.

#### Method 1: `escapeKeydownBehavior` The `escapeKeydownBehavior` prop allows you to customize the behavior taken by the component when the `Escape` key is pressed. It accepts one of the following values:

- `'close'` (default): Closes the Dialog immediately.
- `'ignore'` : Prevents the Dialog from closing.
- `'defer-otherwise-close'` : If an ancestor Bits UI component also implements this prop, it will defer the closing decision to that component. Otherwise, the Dialog will close immediately.
- `'defer-otherwise-ignore'` : If an ancestor Bits UI component also implements this prop, it will defer the closing decision to that component. Otherwise, the Dialog will ignore the key press and not close.

To always prevent the Dialog from closing on Escape key press, set the `escapeKeydownBehavior` prop to `'ignore'` on `Dialog.Content`:

```svelte
<Dialog.Content escapeKeydownBehavior="ignore">
</Dialog.Content>
```

#### Method 2: `onEscapeKeydown` For more granular control, override the default behavior using the `onEscapeKeydown` prop:

```svelte
<Dialog.Content
 onEscapeKeydown={(e) => {
  e.preventDefault();
  // do something else instead
 }}
>
</Dialog.Content>
```

This method allows you to implement custom logic when the `Escape` key is pressed.

### Interaction Outside

By default, interacting outside the Dialog content area closes the Dialog. Bits UI offers two ways to modify this behavior.

#### Method 1: `interactOutsideBehavior` The `interactOutsideBehavior` prop allows you to customize the behavior taken by the component when an interaction (touch, mouse, or pointer event) occurs outside the content. It accepts one of the following values:

- `'close'` (default): Closes the Dialog immediately.
- `'ignore'` : Prevents the Dialog from closing.
- `'defer-otherwise-close'` : If an ancestor Bits UI component also implements this prop, it will defer the closing decision to that component. Otherwise, the Dialog will close immediately.
- `'defer-otherwise-ignore'` : If an ancestor Bits UI component also implements this prop, it will defer the closing decision to that component. Otherwise, the Dialog will ignore the event and not close.

To always prevent the Dialog from closing when an interaction occurs outside the content, set the `interactOutsideBehavior` prop to `'ignore'` on `Dialog.Content`:

```svelte
<Dialog.Content interactOutsideBehavior="ignore">
</Dialog.Content>
```

#### Method 2: `onInteractOutside` For custom handling of outside interactions, you can override the default behavior using the `onInteractOutside` prop:

```svelte
<Dialog.Content
 onInteractOutside={(e) => {
  e.preventDefault();
  // do something else instead
 }}
>
</Dialog.Content>
```

This approach allows you to implement specific behaviors when users interact outside the Dialog content.

### Best Practices

- **Scroll Lock**: Consider your use case carefully before disabling scroll lock. It may be necessary for dialogs with scrollable content or for specific UX requirements.  
- **Escape Keydown**: Overriding the default escape key behavior should be done thoughtfully. Users often expect the escape key to close modals.  
- **Outside Interactions**: Ignoring outside interactions can be useful for important dialogs or multi-step processes, but be cautious not to trap users unintentionally.  
- **Accessibility**: Always ensure that any customizations maintain or enhance the dialog's accessibility.  
- **User Expectations**: Try to balance custom behaviors with common UX patterns to avoid confusing users. By leveraging these advanced features, you can create highly customized dialog experiences while maintaining usability and accessibility standards.

## Nested Dialogs

Dialogs can be nested within each other to create more complex user interfaces:

```svelte
<script lang="ts">
 import MyDialog from "$lib/components/MyDialog.svelte";
</script>
<MyDialog buttonText="Open first dialog">
 {#snippet title()}
  First Dialog
 {/snippet}
 {#snippet description()}
  This is the first dialog.
 {/snippet}
 <MyDialog buttonText="Open second dialog">
  {#snippet title()}
   Second Dialog
  {/snippet}
  {#snippet description()}
   This is the second dialog.
  {/snippet}
 </MyDialog>
</MyDialog>
```

## Svelte Transitions

The Dialog component can be enhanced with Svelte's built-in transition effects or other animation libraries.

### Using `forceMount` and `child` Snippets

To apply Svelte transitions to Dialog components, use the `forceMount` prop in combination with the `child` snippet. This approach gives you full control over the mounting behavior and animation of `Dialog.Content` and `Dialog.Overlay`.

```svelte
<script lang="ts">
 import { Dialog } from "bits-ui";
 import { fly, fade } from "svelte/transition";
</script>
<Dialog.Root>
 <Dialog.Overlay forceMount>
  {#snippet child({ props, open })}
   {#if open}
    <div {...props} transition:fade>
    </div>
   {/if}
  {/snippet}
 </Dialog.Overlay>
 <Dialog.Content forceMount>
  {#snippet child({ props, open })}
   {#if open}
    <div {...props} transition:fly>
    </div>
   {/if}
  {/snippet}
 </Dialog.Content>
</Dialog.Root>
```

In this example:

- The `forceMount` prop ensures the components are always in the DOM.
- The `child` snippet provides access to the open state and component props.
- Svelte's `#if` block controls when the content is visible.
- Transition directives ( `transition:fade` and `transition:fly` ) apply the animations.

### Best Practices

For cleaner code and better maintainability, consider creating custom reusable components that encapsulate this transition logic.

MyDialogOverlay.svelte

```svelte
<script lang="ts">
 import { Dialog, type WithoutChildrenOrChild } from "bits-ui";
 import { fade } from "svelte/transition";
 import type { Snippet } from "svelte";
 let {
  ref = $bindable(null),
  duration = 200,
  children,
  ...restProps
 }: WithoutChildrenOrChild<Dialog.OverlayProps> & {
  duration?: number;
  children?: Snippet;
 } = $props();
</script>
<Dialog.Overlay forceMount bind:ref {...restProps}>
 {#snippet child({ props, open })}
  {#if open}
   <div {...props} transition:fade={{ duration }}>
    {@render children?.()}
   </div>
  {/if}
 {/snippet}
</Dialog.Overlay>
```

You can then use the `MyDialogOverlay` component alongside the other `Dialog` primitives throughout your application:

```svelte
<script lang="ts">
 import { Dialog } from "bits-ui";
 import { MyDialogOverlay } from "$lib/components";
</script>
<Dialog.Root>
 <Dialog.Trigger>Open</Dialog.Trigger>
 <Dialog.Portal>
  <MyDialogOverlay duration={300} />
  <Dialog.Content>
  </Dialog.Content>
 </Dialog.Portal>
</Dialog.Root>
```

## Working with Forms

### Form Submission

When using the `Dialog` component, often you'll want to submit a form or perform an asynchronous action and then close the dialog.

This can be done by waiting for the asynchronous action to complete, then programmatically closing the dialog.

```svelte
<script lang="ts">
 import { Dialog } from "bits-ui";
 function wait(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
 }
 let open = $state(false);
</script>
<Dialog.Root bind:open>
 <Dialog.Portal>
  <Dialog.Overlay />
  <Dialog.Content>
   <Dialog.Title>Confirm your action</Dialog.Title>
   <Dialog.Description>Are you sure you want to do this?</Dialog.Description>
   <form
    method="POST"
    action="?/someAction"
    onsubmit={() => {
     wait(1000).then(() => (open = false));
    }}
   >
    <button type="submit">Submit form</Dialog.Action>
   </form>
  </Dialog.Content>
 </Dialog.Portal>
</Dialog.Root>
```

### Inside a Form

If you're using a `Dialog` *within* a form, you'll need to ensure that the `Portal` is disabled or not included in the `Dialog` structure. This is because the `Portal` will render the dialog content *outside* of the form, which will prevent the form from being submitted correctly.

## API Reference

### Dialog.Root

The root component used to set and manage the state of the dialog.

| Property                                                                                     | Type                                                                                                                                                                                                           | Description                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `open` $bindable | `boolean`                                                                                                                                                           | Whether or not the dialog is open.`Default: false`                                          |
| `onOpenChange`                                             | `function`- (open: boolean) => void | A callback function called when the open state changes.`Default:  undefined`             |
| `children`                                                 | `Snippet`                                                                                                                                                           | The children content to render.`Default:  undefined` |

### Dialog.Trigger

The element which opens the dialog on press.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                      | Value         | Description                                                                                |
| -------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `data-dialog-trigger` | `''` | Present on the trigger. |

### Dialog.Portal

A portal which renders the dialog into the body when it is open.

| Property                                                            | Type                                                                                                                                                                                                                           | Description                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `to` | `union`- string \| HTMLElement \| null \| undefined | Where to render the content when it is open. Defaults to the body. Can be disabled by passing `null``Default: body`              |
| `disabled`                        | `boolean`                                                                                                                                                                           | Whether the portal is disabled or not. When disabled, the content will be rendered in its original DOM location.`Default: false` |
| `children`                        | `Snippet`                                                                                                                                                                           | The children content to render.`Default:  undefined`                                      |

### Dialog.Content

The content displayed within the dialog modal.

| Property                                                                         | Type                                                                                                                                                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onEscapeKeydown` | `function`- (event: KeyboardEvent) => void                                         | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default:  undefined`                                                                                                                                                                                                                    |
| `escapeKeydownBehavior`                        | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` |
| `onInteractOutside`                            | `function`- (event: PointerEvent) => void                                          | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default:  undefined`                                                                                                                                                                                                        |
| `onFocusOutside`                               | `function`- (event: FocusEvent) => void                                            | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default:  undefined`                                                                                                                                                                                                                                                  |
| `interactOutsideBehavior`                      | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close`  |
| `onOpenAutoFocus`                              | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is opened. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `onCloseAutoFocus`                             | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is closed. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `trapFocus`                                    | `boolean`                                                                                                                                                                                                          | Whether or not to trap the focus within the content when open.`Default: true`                                                                                                                                                                                                                                                                                                                                                      |
| `forceMount`                                   | `boolean`                                                                                                                                                                                                          | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                                                                                                                                                                                                                                                                 |
| `preventOverflowTextSelection`                 | `boolean`                                                                                                                                                                                                          | When `true`, prevents the text selection from overflowing the bounds of the element.`Default: true`                                                                                                                                                                                                                                                                                                                                |
| `preventScroll`                                | `boolean`                                                                                                                                                                                                          | When `true`, prevents the body from scrolling when the content is open. This is useful when you want to use the content as a modal.`Default: true`                                                                                                                                                                                                                                                                                 |
| `restoreScrollDelay`                           | `number`                                                                                                                                                                                                           | The delay in milliseconds before the scrollbar is restored after closing the dialog. This is only applicable when using the `child` snippet for custom transitions and `preventScroll` and `forceMount` are `true`. You should set this to a value greater than the transition duration to prevent content from shifting during the transition.`Default: null`                                                                     |
| `ref` $bindable                   | `HTMLDivElement`                                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                                                                                                                                                                         |
| `children`                                     | `Snippet`                                                                                                                                                                                                          | The children content to render.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                                                            |
| `child`                                        | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };               | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                                                                                                                                                                  | | Data Attribute                             | Value                                                                                                                                                                         | Description                                                                                |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `data-state` | `enum`- '' | The state of the dialog.                                            |
| `data-dialog-content`                             | `''`                                                                                                                                                                 | Present on the content. |

### Dialog.Overlay

An overlay which covers the body when the dialog is open.

| Property                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `forceMount` | `boolean`                                                                                                                                                                                            | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                |
| `ref` $bindable              | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value                                                                                                                                                                         | Description                                                                                |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `data-state` | `enum`- '' | The state of the dialog.                                            |
| `data-dialog-overlay`                             | `''`                                                                                                                                                                 | Present on the overlay. |

### Dialog.Close

A button used to close the dialog.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                    | Value         | Description                                                                                     |
| ------------------------------------------------------------------------------------ | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-dialog-close` | `''` | Present on the close button. |

### Dialog.Title

An accessible title for the dialog.

| Property                                                               | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `level` | `union`- 1 \| 2 \| 3 \| 4 \| 5 \| 6                                  | The heading level of the title.`Default: 3`                                                                                                                                       |
| `ref` $bindable         | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                           | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                              | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                    | Value         | Description                                                                              |
| ------------------------------------------------------------------------------------ | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `data-dialog-title` | `''` | Present on the title. |

### Dialog.Description

An accessible description for the dialog.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                          | Value         | Description                                                                                    |
| ------------------------------------------------------------------------------------------ | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `data-dialog-description` | `''` | Present on the description. |

----------------------------------------------------

# Dropdown Menu Documentation

Displays a menu of items that users can select from when triggered.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { Avatar, DropdownMenu } from "bits-ui";
  import Cardholder from "phosphor-svelte/lib/Cardholder";
  import CaretRight from "phosphor-svelte/lib/CaretRight";
  import DotsThree from "phosphor-svelte/lib/DotsThree";
  import GearSix from "phosphor-svelte/lib/GearSix";
  import UserCircle from "phosphor-svelte/lib/UserCircle";
  import UserCirclePlus from "phosphor-svelte/lib/UserCirclePlus";
  import Bell from "phosphor-svelte/lib/Bell";
  import Check from "phosphor-svelte/lib/Check";
  import DotOutline from "phosphor-svelte/lib/DotOutline";
  let notifications = $state<boolean>(false);
  let invited = $state("");
</script>
<DropdownMenu.Root>
  <DropdownMenu.Trigger
    class="focus-visible border-bordinput bg-backgrounder-lt text-a-foreground shadow-btn hover:bg-muted focus-visible:ring-foreground focus-visible:ring-offset-background inline-flex h-10 w-10 select-none items-center justify-center rounded-full border text-sm font-medium focus-visible:ring-2 focus-visible:ring-offset-2 active:scale-[0.98]"
  >
    <DotsThree class="text-foreground h-6 w-6" />
  </DropdownMenu.Trigger>
  <DropdownMenu.Portal>
    <DropdownMenu.Content
      class="focus-override border-muted bg-background shadow-popover outline-hidden focus-visible:outline-hidden w-[229px] rounded-xl border px-1 py-1.5"
      sideOffset={8}
    >
      <DropdownMenu.Item
        class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
      >
        <div class="flex items-center">
          <UserCircle class="text-foreground-alt mr-2 size-5" />
          Profile
        </div>
        <div class="ml-auto flex items-center gap-px">
          <kbd
            class="rounded-button border-dark-10 bg-background-alt text-muted-foreground shadow-kbd inline-flex size-5 items-center justify-center border text-xs"
          >
            
          </kbd>
          <kbd
            class="rounded-button border-dark-10 bg-background-alt text-muted-foreground shadow-kbd inline-flex size-5 items-center justify-center border text-[10px]"
          >
            P
          </kbd>
        </div>
      </DropdownMenu.Item>
      <DropdownMenu.Item
        class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
      >
        <div class="flex items-center">
          <Cardholder class="text-foreground-alt mr-2 size-5" />
          Billing
        </div>
        <div class="ml-auto flex items-center gap-px">
          <kbd
            class="rounded-button border-dark-10 bg-background-alt text-muted-foreground shadow-kbd inline-flex size-5 items-center justify-center border text-xs"
          >
            
          </kbd>
          <kbd
            class="rounded-button border-dark-10 bg-background-alt text-muted-foreground shadow-kbd inline-flex size-5 items-center justify-center border text-[10px]"
          >
            B
          </kbd>
        </div>
      </DropdownMenu.Item>
      <DropdownMenu.Item
        class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
      >
        <div class="flex items-center">
          <GearSix class="text-foreground-alt mr-2 size-5" />
          Settings
        </div>
        <div class="ml-auto flex items-center gap-px">
          <kbd
            class="rounded-button border-dark-10 bg-background-alt text-muted-foreground shadow-kbd inline-flex size-5 items-center justify-center border text-xs"
          >
            
          </kbd>
          <kbd
            class="rounded-button border-dark-10 bg-background-alt text-muted-foreground shadow-kbd inline-flex size-5 items-center justify-center border text-[10px]"
          >
            S
          </kbd>
        </div>
      </DropdownMenu.Item>
      <DropdownMenu.CheckboxItem
        bind:checked={notifications}
        class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
      >
        {#snippet children({ checked })}
          <div class="flex items-center pr-4">
            <Bell class="text-foreground-alt mr-2 size-5" />
            Notifications
          </div>
          <div class="ml-auto flex items-center gap-px">
            {#if checked}
              <Check class="size-4" />
            {/if}
          </div>
        {/snippet}
      </DropdownMenu.CheckboxItem>
      <DropdownMenu.Sub>
        <DropdownMenu.SubTrigger
          class="rounded-button data-highlighted:bg-muted data-[state=open]:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
        >
          <div class="flex items-center">
            <UserCirclePlus class="text-foreground-alt mr-2 size-5" />
            Workspace
          </div>
          <div class="ml-auto flex items-center gap-px">
            <CaretRight class="text-foreground-alt size-5" />
          </div>
        </DropdownMenu.SubTrigger>
        <DropdownMenu.SubContent
          id="subcontent"
          class="border-muted bg-background shadow-popover ring-0! ring-transparent! w-[209px] rounded-xl border px-1 py-1.5"
          sideOffset={10}
        >
          <DropdownMenu.RadioGroup bind:value={invited}>
            <DropdownMenu.RadioItem
              value="huntabyte"
              class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
            >
              {#snippet children({ checked })}
                <Avatar.Root
                  class="border-foreground/50 relative mr-3 flex size-5 shrink-0 overflow-hidden rounded-full border"
                >
                  <Avatar.Image
                    src="https://github.com/huntabyte.png"
                    alt="@huntabyte"
                    class="aspect-square h-full w-full"
                  />
                  <Avatar.Fallback
                    class="bg-muted text-xxs flex h-full w-full items-center justify-center rounded-full"
                    >HJ</Avatar.Fallback
                  >
                </Avatar.Root>
                @huntabyte
                {#if checked}
                  <DotOutline class="ml-auto size-4" />
                {/if}
              {/snippet}
            </DropdownMenu.RadioItem>
            <DropdownMenu.RadioItem
              value="pavel"
              class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
            >
              {#snippet children({ checked })}
                <Avatar.Root
                  class="border-foreground/50 relative mr-3 flex size-5 shrink-0 overflow-hidden rounded-full border"
                >
                  <Avatar.Image
                    src="https://github.com/pavelstianko.png"
                    alt="@pavel_stianko"
                    class="aspect-square h-full w-full"
                  />
                  <Avatar.Fallback
                    class="bg-muted flex h-full w-full items-center justify-center rounded-full text-xs"
                    >PS</Avatar.Fallback
                  >
                </Avatar.Root>
                @pavel_stianko
                {#if checked}
                  <DotOutline class="ml-auto size-4" />
                {/if}
              {/snippet}
            </DropdownMenu.RadioItem>
            <DropdownMenu.RadioItem
              value="cokakoala"
              class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
            >
              {#snippet children({ checked })}
                <Avatar.Root
                  class="border-foreground/50 relative mr-3 flex size-5 shrink-0 overflow-hidden rounded-full border"
                >
                  <Avatar.Image
                    src="https://github.com/adriangonz97.png"
                    alt="@cokakoala_"
                    class="aspect-square h-full w-full"
                  />
                  <Avatar.Fallback
                    class="bg-muted flex h-full w-full items-center justify-center rounded-full text-xs"
                    >CK</Avatar.Fallback
                  >
                </Avatar.Root>
                @cokakoala_
                {#if checked}
                  <DotOutline class="ml-auto size-4" />
                {/if}
              {/snippet}
            </DropdownMenu.RadioItem>
            <DropdownMenu.RadioItem
              value="tglide"
              class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
            >
              {#snippet children({ checked })}
                <Avatar.Root
                  class="border-foreground/50 relative mr-3 flex size-5 shrink-0 overflow-hidden rounded-full border"
                >
                  <Avatar.Image
                    src="https://github.com/tglide.png"
                    alt="@tglide"
                    class="aspect-square h-full w-full"
                  />
                  <Avatar.Fallback
                    class="bg-muted flex h-full w-full items-center justify-center rounded-full text-xs"
                  >
                    TL
                  </Avatar.Fallback>
                </Avatar.Root>
                @thomasglopes
                {#if checked}
                  <DotOutline class="ml-auto size-4" />
                {/if}
              {/snippet}
            </DropdownMenu.RadioItem>
          </DropdownMenu.RadioGroup>
        </DropdownMenu.SubContent>
      </DropdownMenu.Sub>
    </DropdownMenu.Content>
  </DropdownMenu.Portal>
</DropdownMenu.Root>
```

## Structure

```svelte
<script lang="ts">
 import { DropdownMenu } from "bits-ui";
</script>
<DropdownMenu.Root>
 <DropdownMenu.Trigger />
 <DropdownMenu.Content>
  <DropdownMenu.Group>
   <DropdownMenu.GroupHeading />
   <DropdownMenu.Item />
  </DropdownMenu.Group>
  <DropdownMenu.Group>
   <DropdownMenu.Item />
  </DropdownMenu.Group>
  <DropdownMenu.CheckboxItem>
   <DropdownMenu.CheckboxIndicator />
  </DropdownMenu.CheckboxItem>
  <DropdownMenu.RadioGroup>
   <DropdownMenu.RadioItem>
    <DropdownMenu.RadioIndicator />
   </DropdownMenu.RadioItem>
  </DropdownMenu.RadioGroup>
  <DropdownMenu.Sub>
   <DropdownMenu.SubTrigger />
   <DropdownMenu.SubContent />
  </DropdownMenu.Sub>
  <DropdownMenu.Separator />
  <DropdownMenu.Arrow />
 </DropdownMenu.Content>
</DropdownMenu.Root>
```

## Reusable Components

If you're planning to use Dropdown Menu in multiple places, you can create a reusable component that wraps the Dropdown Menu component.

This example shows you how to create a Dropdown Menu component that accepts a few custom props that make it more capable.

MyDropdownMenu.svelte

```svelte
<script lang="ts">
 import type { Snippet } from "svelte";
 import { DropdownMenu, type WithoutChild } from "bits-ui";
 type Props = DropdownMenu.Props & {
  buttonText: string;
  items: string[];
  contentProps?: WithoutChild<DropdownMenu.Content.Props>;
  // other component props if needed
 };
 let {
  open = $bindable(false),
  children,
  buttonText,
  items,
  contentProps,
  ...restProps
 }: Props = $props();
</script>
<DropdownMenu.Root bind:open {...restProps}>
 <DropdownMenu.Trigger>
  {buttonText}
 </DropdownMenu.Trigger>
 <DropdownMenu.Portal>
  <DropdownMenu.Content {...contentProps}>
   <DropdownMenu.Group aria-label={buttonText}>
    {#each items as item}
     <DropdownMenu.Item textValue={item}>
      {item}
     </DropdownMenu.Item>
    {/each}
   </DropdownMenu.Group>
  </DropdownMenu.Content>
 </DropdownMenu.Portal>
</DropdownMenu.Root>
```

You can then use the `MyDropdownMenu` component like this:

```svelte
<script lang="ts">
 import MyDropdownMenu from "./MyDropdownMenu.svelte";
</script>
<MyDropdownMenu
 buttonText="Select a manager"
 items={["Michael Scott", "Dwight Schrute", "Jim Halpert"]}
/>
```

## Managing Open State

This section covers how to manage the `open` state of the menu.

### Two-Way Binding

Use `bind:open` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { DropdownMenu } from "bits-ui";
 let isOpen = $state(false);
</script>
<button onclick={() => (isOpen = true)}>Open Context Menu</button>
<DropdownMenu.Root bind:open={isOpen}>
</DropdownMenu.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { DropdownMenu } from "bits-ui";
 let myOpen = $state(false);
 function getOpen() {
  return myOpen;
 }
 function setOpen(newOpen: boolean) {
  myOpen = newOpen;
 }
</script>
<DropdownMenu.Root bind:open={getOpen, setOpen}>
</DropdownMenu.Root>
```

## Groups

To group related menu items, you can use the `DropdownMenu.Group` component along with either a `DropdownMenu.GroupHeading` or an `aria-label` attribute on the `DropdownMenu.Group` component.

```svelte
<DropdownMenu.Group>
 <DropdownMenu.GroupHeading>File</DropdownMenu.GroupHeading>
 <DropdownMenu.Item>New</DropdownMenu.Item>
 <DropdownMenu.Item>Open</DropdownMenu.Item>
 <DropdownMenu.Item>Save</DropdownMenu.Item>
 <DropdownMenu.Item>Save As</DropdownMenu.Item>
</DropdownMenu.Group>

<DropdownMenu.Group aria-label="file">
 <DropdownMenu.Item>New</DropdownMenu.Item>
 <DropdownMenu.Item>Open</DropdownMenu.Item>
 <DropdownMenu.Item>Save</DropdownMenu.Item>
 <DropdownMenu.Item>Save As</DropdownMenu.Item>
</DropdownMenu.Group>
```

### Group Heading

The `DropdownMenu.GroupHeading` component must be a child of either a `DropdownMenu.Group` or `DropdownMenu.RadioGroup` component. If used on its own, an error will be thrown during development.

```svelte
<DropdownMenu.Group>
 <DropdownMenu.GroupHeading>File</DropdownMenu.GroupHeading>
</DropdownMenu.Group>

<DropdownMenu.RadioGroup>
 <DropdownMenu.GroupHeading>Favorite color</DropdownMenu.GroupHeading>
</DropdownMenu.RadioGroup>
```

## Checkbox Items

You can use the `DropdownMenu.CheckboxItem` component to create a `menuitemcheckbox` element to add checkbox functionality to menu items.

```svelte
<script lang="ts">
 import { DropdownMenu } from "bits-ui";
 let notifications = $state(true);
</script>
<DropdownMenu.CheckboxItem bind:checked={notifications}>
 {#snippet children({ checked, indeterminate })}
  {#if indeterminate}
   -
  {:else if checked}
   
  {/if}
  Notifications
 {/snippet}
</DropdownMenu.CheckboxItem>
```

The `checked` state does not persist between menu open/close cycles. To persist the state, you must store it in a `$state` variable and pass it to the `checked` prop.

## Radio Groups

You can combine the `DropdownMenu.RadioGroup` and `DropdownMenu.RadioItem` components to create a radio group within a menu.

```svelte
<script lang="ts">
 import { DropdownMenu } from "bits-ui";
 const values = ["one", "two", "three"];
 let value = $state("one");
</script>
<DropdownMenu.RadioGroup bind:value>
 <DropdownMenu.GroupHeading>Favorite number</DropdownMenu.GroupHeading>
 {#each values as value}
  <DropdownMenu.RadioItem {value}>
   {#snippet children({ checked })}
    {#if checked}
     
    {/if}
    {value}
   {/snippet}
  </DropdownMenu.RadioItem>
 {/each}
</DropdownMenu.RadioGroup>
```

The `value` state does not persist between menu open/close cycles. To persist the state, you must store it in a `$state` variable and pass it to the `value` prop.

## Nested Menus

You can create nested menus using the `DropdownMenu.Sub` component to create complex menu structures.

```svelte
<script lang="ts">
 import { DropdownMenu } from "bits-ui";
</script>
<DropdownMenu.Content>
 <DropdownMenu.Item>Item 1</DropdownMenu.Item>
 <DropdownMenu.Item>Item 2</DropdownMenu.Item>
 <DropdownMenu.Sub>
  <DropdownMenu.SubTrigger>Open Sub Menu</DropdownMenu.SubTrigger>
  <DropdownMenu.SubContent>
   <DropdownMenu.Item>Sub Item 1</DropdownMenu.Item>
   <DropdownMenu.Item>Sub Item 2</DropdownMenu.Item>
  </DropdownMenu.SubContent>
 </DropdownMenu.Sub>
</DropdownMenu.Content>
```

## Svelte Transitions

You can use the `forceMount` prop along with the `child` snippet to forcefully mount the `DropdownMenu.Content` component to use Svelte Transitions or another animation library that requires more control.

```svelte
<script lang="ts">
 import { DropdownMenu } from "bits-ui";
 import { fly } from "svelte/transition";
</script>
<DropdownMenu.Content forceMount>
 {#snippet child({ wrapperProps, props, open })}
  {#if open}
   <div {...wrapperProps}>
    <div {...props} transition:fly>
     <DropdownMenu.Item>Item 1</DropdownMenu.Item>
     <DropdownMenu.Item>Item 2</DropdownMenu.Item>
    </div>
   </div>
  {/if}
 {/snippet}
</DropdownMenu.Content>
```

Of course, this isn't the prettiest syntax, so it's recommended to create your own reusable content component that handles this logic if you intend to use this approach. For more information on using transitions with Bits UI components, see the [Transitions](/docs/transitions) documentation.

```svelte
<script lang="ts">
  import { Avatar, DropdownMenu } from "bits-ui";
  import Cardholder from "phosphor-svelte/lib/Cardholder";
  import CaretRight from "phosphor-svelte/lib/CaretRight";
  import DotsThree from "phosphor-svelte/lib/DotsThree";
  import GearSix from "phosphor-svelte/lib/GearSix";
  import UserCircle from "phosphor-svelte/lib/UserCircle";
  import UserCirclePlus from "phosphor-svelte/lib/UserCirclePlus";
  import Bell from "phosphor-svelte/lib/Bell";
  import Check from "phosphor-svelte/lib/Check";
  import DotOutline from "phosphor-svelte/lib/DotOutline";
  import { fly } from "svelte/transition";
  let notifications = $state<boolean>(false);
  let invited = $state("");
</script>
<DropdownMenu.Root>
  <DropdownMenu.Trigger
    class="focus-visible border-bordinput bg-backgrounder-lt text-a-foreground shadow-btn hover:bg-muted focus-visible:ring-foreground focus-visible:ring-offset-background inline-flex h-10 w-10 select-none items-center justify-center rounded-full border text-sm font-medium focus-visible:ring-2 focus-visible:ring-offset-2 active:scale-[0.98]"
  >
    <DotsThree class="text-foreground h-6 w-6" />
  </DropdownMenu.Trigger>
  <DropdownMenu.Portal>
    <DropdownMenu.Content
      class="focus-override border-muted bg-background shadow-popover outline-hidden focus-visible:outline-hidden w-[229px] rounded-xl border px-1 py-1.5"
      sideOffset={8}
      forceMount
    >
      {#snippet child({ wrapperProps, props, open })}
        {#if open}
          <div {...wrapperProps}>
            <div {...props} transition:fly={{ duration: 300 }}>
              <DropdownMenu.Item
                class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
              >
                <div class="flex items-center">
                  <UserCircle class="text-foreground-alt mr-2 size-5" />
                  Profile
                </div>
                <div class="ml-auto flex items-center gap-px">
                  <kbd
                    class="rounded-button border-dark-10 bg-background-alt text-muted-foreground shadow-kbd inline-flex size-5 items-center justify-center border text-xs"
                  >
                    
                  </kbd>
                  <kbd
                    class="rounded-button border-dark-10 bg-background-alt text-muted-foreground shadow-kbd inline-flex size-5 items-center justify-center border text-[10px]"
                  >
                    P
                  </kbd>
                </div>
              </DropdownMenu.Item>
              <DropdownMenu.Item
                class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
              >
                <div class="flex items-center">
                  <Cardholder class="text-foreground-alt mr-2 size-5" />
                  Billing
                </div>
                <div class="ml-auto flex items-center gap-px">
                  <kbd
                    class="rounded-button border-dark-10 bg-background-alt text-muted-foreground shadow-kbd inline-flex size-5 items-center justify-center border text-xs"
                  >
                    
                  </kbd>
                  <kbd
                    class="rounded-button border-dark-10 bg-background-alt text-muted-foreground shadow-kbd inline-flex size-5 items-center justify-center border text-[10px]"
                  >
                    B
                  </kbd>
                </div>
              </DropdownMenu.Item>
              <DropdownMenu.Item
                class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
              >
                <div class="flex items-center">
                  <GearSix class="text-foreground-alt mr-2 size-5" />
                  Settings
                </div>
                <div class="ml-auto flex items-center gap-px">
                  <kbd
                    class="rounded-button border-dark-10 bg-background-alt text-muted-foreground shadow-kbd inline-flex size-5 items-center justify-center border text-xs"
                  >
                    
                  </kbd>
                  <kbd
                    class="rounded-button border-dark-10 bg-background-alt text-muted-foreground shadow-kbd inline-flex size-5 items-center justify-center border text-[10px]"
                  >
                    S
                  </kbd>
                </div>
              </DropdownMenu.Item>
              <DropdownMenu.CheckboxItem
                bind:checked={notifications}
                class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
              >
                {#snippet children({ checked })}
                  <div class="flex items-center pr-4">
                    <Bell class="text-foreground-alt mr-2 size-5" />
                    Notifications
                  </div>
                  <div class="ml-auto flex items-center gap-px">
                    {#if checked}
                      <Check class="size-4" />
                    {/if}
                  </div>
                {/snippet}
              </DropdownMenu.CheckboxItem>
              <DropdownMenu.Sub>
                <DropdownMenu.SubTrigger
                  class="rounded-button data-highlighted:bg-muted data-[state=open]:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
                >
                  <div class="flex items-center">
                    <UserCirclePlus class="text-foreground-alt mr-2 size-5" />
                    Workspace
                  </div>
                  <div class="ml-auto flex items-center gap-px">
                    <CaretRight class="text-foreground-alt size-5" />
                  </div>
                </DropdownMenu.SubTrigger>
                <DropdownMenu.SubContent
                  id="subcontent"
                  class="border-muted bg-background shadow-popover ring-0! ring-transparent! w-[209px] rounded-xl border px-1 py-1.5"
                  sideOffset={10}
                >
                  <DropdownMenu.RadioGroup bind:value={invited}>
                    <DropdownMenu.RadioItem
                      value="huntabyte"
                      class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
                    >
                      {#snippet children({ checked })}
                        <Avatar.Root
                          class="border-foreground/50 relative mr-3 flex size-5 shrink-0 overflow-hidden rounded-full border"
                        >
                          <Avatar.Image
                            src="https://github.com/huntabyte.png"
                            alt="@huntabyte"
                            class="aspect-square h-full w-full"
                          />
                          <Avatar.Fallback
                            class="bg-muted text-xxs flex h-full w-full items-center justify-center rounded-full"
                            >HJ</Avatar.Fallback
                          >
                        </Avatar.Root>
                        @huntabyte
                        {#if checked}
                          <DotOutline class="ml-auto size-4" />
                        {/if}
                      {/snippet}
                    </DropdownMenu.RadioItem>
                    <DropdownMenu.RadioItem
                      value="pavel"
                      class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
                    >
                      {#snippet children({ checked })}
                        <Avatar.Root
                          class="border-foreground/50 relative mr-3 flex size-5 shrink-0 overflow-hidden rounded-full border"
                        >
                          <Avatar.Image
                            src="https://github.com/pavelstianko.png"
                            alt="@pavel_stianko"
                            class="aspect-square h-full w-full"
                          />
                          <Avatar.Fallback
                            class="bg-muted flex h-full w-full items-center justify-center rounded-full text-xs"
                            >PS</Avatar.Fallback
                          >
                        </Avatar.Root>
                        @pavel_stianko
                        {#if checked}
                          <DotOutline class="ml-auto size-4" />
                        {/if}
                      {/snippet}
                    </DropdownMenu.RadioItem>
                    <DropdownMenu.RadioItem
                      value="cokakoala"
                      class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
                    >
                      {#snippet children({ checked })}
                        <Avatar.Root
                          class="border-foreground/50 relative mr-3 flex size-5 shrink-0 overflow-hidden rounded-full border"
                        >
                          <Avatar.Image
                            src="https://github.com/adriangonz97.png"
                            alt="@cokakoala_"
                            class="aspect-square h-full w-full"
                          />
                          <Avatar.Fallback
                            class="bg-muted flex h-full w-full items-center justify-center rounded-full text-xs"
                            >CK</Avatar.Fallback
                          >
                        </Avatar.Root>
                        @cokakoala_
                        {#if checked}
                          <DotOutline class="ml-auto size-4" />
                        {/if}
                      {/snippet}
                    </DropdownMenu.RadioItem>
                    <DropdownMenu.RadioItem
                      value="tglide"
                      class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
                    >
                      {#snippet children({ checked })}
                        <Avatar.Root
                          class="border-foreground/50 relative mr-3 flex size-5 shrink-0 overflow-hidden rounded-full border"
                        >
                          <Avatar.Image
                            src="https://github.com/tglide.png"
                            alt="@tglide"
                            class="aspect-square h-full w-full"
                          />
                          <Avatar.Fallback
                            class="bg-muted flex h-full w-full items-center justify-center rounded-full text-xs"
                          >
                            TL
                          </Avatar.Fallback>
                        </Avatar.Root>
                        @thomasglopes
                        {#if checked}
                          <DotOutline class="ml-auto size-4" />
                        {/if}
                      {/snippet}
                    </DropdownMenu.RadioItem>
                  </DropdownMenu.RadioGroup>
                </DropdownMenu.SubContent>
              </DropdownMenu.Sub>
            </div>
          </div>
        {/if}
      {/snippet}
    </DropdownMenu.Content>
  </DropdownMenu.Portal>
</DropdownMenu.Root>
```

## Custom Anchor

By default, the `DropdownMenu.Content` is anchored to the `DropdownMenu.Trigger` component, which determines where the content is positioned.

If you wish to instead anchor the content to a different element, you can pass either a selector `string` or an `HTMLElement` to the `customAnchor` prop of the `DropdownMenu.Content` component.

```svelte
<script lang="ts">
 import { DropdownMenu } from "bits-ui";
 let customAnchor = $state<HTMLElement>(null!);
</script>
<div bind:this={customAnchor}></div>
<DropdownMenu.Root>
 <DropdownMenu.Trigger />
 <DropdownMenu.Content {customAnchor}>
 </DropdownMenu.Content>
</DropdownMenu.Root>
```

## API Reference

### DropdownMenu.Root

The root component which manages & scopes the state of the dropdown menu.

| Property                                                                                     | Type                                                                                                                                                                                                           | Description                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `open` $bindable | `boolean`                                                                                                                                                           | The open state of the menu.`Default: false`                                                 |
| `onOpenChange`                                             | `function`- (open: boolean) => void | A callback that is fired when the menu's open state changes.`Default:  undefined`        |
| `dir`                                                      | `enum`- 'ltr' \| 'rtl'              | The reading direction of the app.`Default: 'ltr'`                                           |
| `children`                                                 | `Snippet`                                                                                                                                                           | The children content to render.`Default:  undefined` |

### DropdownMenu.Trigger

The button element which toggles the dropdown menu.

| Property                                                                  | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `disabled` | `boolean`                                                                                                                                                                                            | Whether or not the menu trigger is disabled.`Default: false`                                                                                                                      |
| `ref` $bindable            | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                              | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                 | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                        |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | The open state of the menu or submenu the element controls or belongs to.   |
| `data-menu-trigger`                               | `''`                                                                                                                                                                                 | Present on the trigger element. |

### DropdownMenu.Portal

A component that portals the content of the dropdown menu to the body or a custom target (if provided).

| Property                                                            | Type                                                                                                                                                                                                                           | Description                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `to` | `union`- string \| HTMLElement \| null \| undefined | Where to render the content when it is open. Defaults to the body. Can be disabled by passing `null``Default: body`              |
| `disabled`                        | `boolean`                                                                                                                                                                           | Whether the portal is disabled or not. When disabled, the content will be rendered in its original DOM location.`Default: false` |
| `children`                        | `Snippet`                                                                                                                                                                           | The children content to render.`Default:  undefined`                                      |

### DropdownMenu.Content

The content displayed when the dropdown menu is open.

| Property                                                              | Type                                                                                                                                                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `side` | `enum`- 'top' \| 'bottom' \| 'left' \| 'right'                                     | The preferred side of the anchor to render the floating element against when open. Will be reversed when collisions occur.`Default: bottom`                                                                                                                                                                                                                                                                                        |
| `sideOffset`                        | `number`                                                                                                                                                                                                           | The distance in pixels from the anchor to the floating element.`Default: 0`                                                                                                                                                                                                                                                                                                                                                        |
| `align`                             | `enum`- 'start' \| 'center' \| 'end'                                               | The preferred alignment of the anchor to render the floating element against when open. This may change when collisions occur.`Default: start`                                                                                                                                                                                                                                                                                     |
| `alignOffset`                       | `number`                                                                                                                                                                                                           | The distance in pixels from the anchor to the floating element.`Default: 0`                                                                                                                                                                                                                                                                                                                                                        |
| `arrowPadding`                      | `number`                                                                                                                                                                                                           | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0`                                                                                                                                                                                                                                                                                                  |
| `avoidCollisions`                   | `boolean`                                                                                                                                                                                                          | When `true`, overrides the `side` and `align` options to prevent collisions with the boundary edges.`Default: true`                                                                                                                                                                                                                                                                                                                |
| `collisionBoundary`                 | `union`- Element \| null                                                           | A boundary element or array of elements to check for collisions against.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                   |
| `collisionPadding`                  | `union`- number \| Partial\&lt;Record\&lt;Side, number\&gt;\&gt;                   | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0`                                                                                                                                                                                                                                                                                                  |
| `sticky`                            | `enum`- 'partial' \| 'always'                                                      | The sticky behavior on the align axis. `'partial'` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst `'always'` will keep the content in the boundary regardless.`Default: partial`                                                                                                                                                                                        |
| `hideWhenDetached`                  | `boolean`                                                                                                                                                                                                          | When `true`, hides the content when it is detached from the DOM. This is useful for when you want to hide the content when the user scrolls away.`Default: true`                                                                                                                                                                                                                                                                   |
| `updatePositionStrategy`            | `enum`- 'optimized' \| 'always'                                                    | The strategy to use when updating the position of the content. When `'optimized'` the content will only be repositioned when the trigger is in the viewport. When `'always'` the content will be repositioned whenever the position changes.`Default: optimized`                                                                                                                                                                   |
| `strategy`                          | `enum`- 'fixed' \| 'absolute'                                                      | The positioning strategy to use for the floating element. When `'fixed'` the element will be positioned relative to the viewport. When `'absolute'` the element will be positioned relative to the nearest positioned ancestor.`Default: fixed`                                                                                                                                                                                    |
| `preventScroll`                     | `boolean`                                                                                                                                                                                                          | When `true`, prevents the body from scrolling when the content is open. This is useful when you want to use the content as a modal.`Default: true`                                                                                                                                                                                                                                                                                 |
| `customAnchor`                      | `union`- string \| HTMLElement \| Measurable \| null                               | Use an element other than the trigger to anchor the content to. If provided, the content will be anchored to the provided element instead of the trigger.`Default: null`                                                                                                                                                                                                                                                           |
| `onEscapeKeydown`                   | `function`- (event: KeyboardEvent) => void                                         | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default:  undefined`                                                                                                                                                                                                                    |
| `escapeKeydownBehavior`             | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` |
| `onInteractOutside`                 | `function`- (event: PointerEvent) => void                                          | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default:  undefined`                                                                                                                                                                                                        |
| `onFocusOutside`                    | `function`- (event: FocusEvent) => void                                            | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default:  undefined`                                                                                                                                                                                                                                                  |
| `interactOutsideBehavior`           | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close`  |
| `onOpenAutoFocus`                   | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is opened. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `onCloseAutoFocus`                  | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is closed. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `trapFocus`                         | `boolean`                                                                                                                                                                                                          | Whether or not to trap the focus within the content when open.`Default: true`                                                                                                                                                                                                                                                                                                                                                      |
| `forceMount`                        | `boolean`                                                                                                                                                                                                          | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                                                                                                                                                                                                                                                                 |
| `preventOverflowTextSelection`      | `boolean`                                                                                                                                                                                                          | When `true`, prevents the text selection from overflowing the bounds of the element.`Default: true`                                                                                                                                                                                                                                                                                                                                |
| `dir`                               | `enum`- 'ltr' \| 'rtl'                                                             | The reading direction of the app.`Default: 'ltr'`                                                                                                                                                                                                                                                                                                                                                                                  |
| `loop`                              | `boolean`                                                                                                                                                                                                          | Whether or not to loop through the menu items in when navigating with the keyboard.`Default: false`                                                                                                                                                                                                                                                                                                                                |
| `ref` $bindable        | `HTMLDivElement`                                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                                                                                                                                                                         |
| `children`                          | `Snippet`- Snippet                                                                 | The children content to render.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                                                            |
| `child`                             | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };               | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                                                                                                                                                                  | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                        |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | The open state of the menu or submenu the element controls or belongs to.   |
| `data-menu-content`                               | `''`                                                                                                                                                                                 | Present on the content element. |

| CSS Variable                                                                  | Description                                                                                                         |
| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--bits-dropdown-menu-content-transform-origin` | The transform origin of the dropdown menu content element.                                   |
| `--bits-dropdown-menu-content-available-width`                                       | The available width of the dropdown menu content element.                                    |
| `--bits-dropdown-menu-content-available-height`                                      | The available height of the dropdown menu content element.                                   |
| `--bits-dropdown-menu-anchor-width`                                                  | The width of the dropdown menu trigger element.                                              |
| `--bits-dropdown-menu-anchor-height`                                                 | The height of the dropdown menu trigger element. |

### DropdownMenu.ContentStatic

The content displayed when the dropdown menu is open. (Static/No Floating UI)

| Property                                                                         | Type                                                                                                                                                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onEscapeKeydown` | `function`- (event: KeyboardEvent) => void                                         | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default:  undefined`                                                                                                                                                                                                                    |
| `escapeKeydownBehavior`                        | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` |
| `onInteractOutside`                            | `function`- (event: PointerEvent) => void                                          | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default:  undefined`                                                                                                                                                                                                        |
| `onFocusOutside`                               | `function`- (event: FocusEvent) => void                                            | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default:  undefined`                                                                                                                                                                                                                                                  |
| `interactOutsideBehavior`                      | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close`  |
| `onOpenAutoFocus`                              | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is opened. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `onCloseAutoFocus`                             | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is closed. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `trapFocus`                                    | `boolean`                                                                                                                                                                                                          | Whether or not to trap the focus within the content when open.`Default: true`                                                                                                                                                                                                                                                                                                                                                      |
| `preventScroll`                                | `boolean`                                                                                                                                                                                                          | When `true`, prevents the body from scrolling when the content is open. This is useful when you want to use the content as a modal.`Default: true`                                                                                                                                                                                                                                                                                 |
| `forceMount`                                   | `boolean`                                                                                                                                                                                                          | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                                                                                                                                                                                                                                                                 |
| `preventOverflowTextSelection`                 | `boolean`                                                                                                                                                                                                          | When `true`, prevents the text selection from overflowing the bounds of the element.`Default: true`                                                                                                                                                                                                                                                                                                                                |
| `dir`                                          | `enum`- 'ltr' \| 'rtl'                                                             | The reading direction of the app.`Default: 'ltr'`                                                                                                                                                                                                                                                                                                                                                                                  |
| `loop`                                         | `boolean`                                                                                                                                                                                                          | Whether or not to loop through the menu items in when navigating with the keyboard.`Default: false`                                                                                                                                                                                                                                                                                                                                |
| `ref` $bindable                   | `HTMLDivElement`                                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                                                                                                                                                                         |
| `children`                                     | `Snippet`- Snippet                                                                 | The children content to render.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                                                            |
| `child`                                        | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };               | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                                                                                                                                                                  | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                        |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | The open state of the menu or submenu the element controls or belongs to.   |
| `data-menu-content`                               | `''`                                                                                                                                                                                 | Present on the content element. |

### DropdownMenu.Item

A menu item within the dropdown menu.

| Property                                                                  | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `disabled` | `boolean`                                                                                                                                                                                            | Whether or not the menu item is disabled.`Default: false`                                                                                                                         |
| `textValue`                             | `string`                                                                                                                                                                                             | The text value of the checkbox menu item. This is used for typeahead.`Default:  undefined`                                                                                     |
| `onSelect`                              | `function`- () => void                                               | A callback that is fired when the menu item is selected.`Default:  undefined`                                                                                                  |
| `closeOnSelect`                         | `boolean`                                                                                                                                                                                            | Whether or not the menu item should close when selected.`Default: true`                                                                                                           |
| `ref` $bindable            | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                              | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                 | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                   | Value                 | Description                                                                                     |
| ----------------------------------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-orientation` | `'vertical'` |                                                                                       |
| `data-highlighted`                                      | `''`         | Present when the menu item is highlighted.                               |
| `data-disabled`                                         | `''`         | Present when the menu item is disabled.                                  |
| `data-menu-item`                                        | `''`         | Present on the item element. |

### DropdownMenu.CheckboxItem

A menu item that can be controlled and toggled like a checkbox.

| Property                                                                  | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `disabled` | `boolean`                                                                                                                                                                                            | Whether or not the checkbox menu item is disabled. Disabled items cannot be interacted with and are skipped when navigating with the keyboard.`Default: false`                    |
| `checked` $bindable        | `boolean`                                                                                                                                                                                            | The checkbox menu item's checked state.`Default: false`                                                                                                                           |
| `onCheckedChange`                       | `function`- (checked: boolean) => void                               | A callback that is fired when the checkbox menu item's checked state changes.`Default:  undefined`                                                                             |
| `indeterminate` $bindable  | `boolean`                                                                                                                                                                                            | Whether the checkbox menu item is in an indeterminate state or not.`Default: false`                                                                                               |
| `onIndeterminateChange`                 | `function`- (indeterminate: boolean) => void                         | A callback that is fired when the indeterminate state changes.`Default:  undefined`                                                                                            |
| `textValue`                             | `string`                                                                                                                                                                                             | The text value of the checkbox menu item. This is used for typeahead.`Default:  undefined`                                                                                     |
| `onSelect`                              | `function`- () => void                                               | A callback that is fired when the menu item is selected.`Default:  undefined`                                                                                                  |
| `closeOnSelect`                         | `boolean`                                                                                                                                                                                            | Whether or not the menu item should close when selected.`Default: true`                                                                                                           |
| `ref` $bindable            | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                              | `Snippet`- Snippet                                                   | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                 | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                   | Value                                                                                                                                                                         | Description                                                                                                |
| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-orientation` | `'vertical'`                                                                                                                                                         |                                                                                                  |
| `data-highlighted`                                      | `''`                                                                                                                                                                 | Present when the menu item is highlighted.                                          |
| `data-disabled`                                         | `''`                                                                                                                                                                 | Present when the menu item is disabled.                                             |
| `data-state`                                            | `enum`- '' | The checkbox menu item's checked state. | ### DropdownMenu.RadioGroup

A group of radio menu items, where only one can be checked at a time.

| Property                                                                                      | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` $bindable | `string`                                                                                                                                                                                             | The value of the currently checked radio menu item.`Default:  undefined`                                                                                                       |
| `onValueChange`                                             | `function`- (value: string) => void                                  | A callback that is fired when the radio group's value changes.`Default:  undefined`                                                                                            |
| `ref` $bindable                                | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                  | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                     | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                        | Value         | Description                                                                                            |
| ---------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-menu-radio-group` | `''` | Present on the radio group element. |

### DropdownMenu.RadioItem

A menu item that can be controlled and toggled like a radio button. It must be a child of a `RadioGroup`.

| Property                                                                                     | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` required | `string`                                                                                                                                                                                             | The value of the radio item. When checked, the parent `RadioGroup`'s value will be set to this value.`Default:  undefined`                                                     |
| `disabled`                                                 | `boolean`                                                                                                                                                                                            | Whether or not the radio menu item is disabled. Disabled items cannot be interacted with and are skipped when navigating with the keyboard.`Default: false`                       |
| `textValue`                                                | `string`                                                                                                                                                                                             | The text value of the checkbox menu item. This is used for typeahead.`Default:  undefined`                                                                                     |
| `onSelect`                                                 | `function`- () => void                                               | A callback that is fired when the menu item is selected.`Default:  undefined`                                                                                                  |
| `closeOnSelect`                                            | `boolean`                                                                                                                                                                                            | Whether or not the menu item should close when selected.`Default: true`                                                                                                           |
| `ref` $bindable                               | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                 | `Snippet`- Snippet                                                   | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                    | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                   | Value                                                                                                                                                                         | Description                                                                                           |
| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-orientation` | `'vertical'`                                                                                                                                                         |                                                                                             |
| `data-highlighted`                                      | `''`                                                                                                                                                                 | Present when the menu item is highlighted.                                     |
| `data-disabled`                                         | `''`                                                                                                                                                                 | Present when the menu item is disabled.                                        |
| `data-state`                                            | `enum`- '' | The radio menu item's checked state.                                           |
| `data-value`                                            | `''`                                                                                                                                                                 | The value of the radio item.                                                   |
| `data-menu-radio-item`                                  | `''`                                                                                                                                                                 | Present on the radio item element. |

### DropdownMenu.Separator

A horizontal line to visually separate menu items.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                   | Value                 | Description                                                                                          |
| ----------------------------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-orientation` | `'vertical'` | The orientation of the separator.                                             |
| `data-menu-separator`                                   | `''`         | Present on the separator element. |

### DropdownMenu.Arrow

An optional arrow which points to the dropdown menu's anchor/trigger point.

| Property                                                               | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `width` | `number`                                                                                                                                                                                             | The width of the arrow in pixels.`Default: 8`                                                                                                                                     |
| `height`                             | `number`                                                                                                                                                                                             | The height of the arrow in pixels.`Default: 8`                                                                                                                                    |
| `ref` $bindable         | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                           | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                              | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                      |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-state` | `enum`- 'open' \| 'closed' | The open state of the menu or submenu the element controls or belongs to. |
| `data-menu-arrow`                                 | `''`                                                                                                                                                                                 | Present on the arrow element. |

### DropdownMenu.Group

A group of menu items. It should be passed an `aria-label` or have a child `Menu.GroupHeading` component to provide a label for a group of menu items.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                  | Value         | Description                                                                                      |
| ---------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-menu-group` | `''` | Present on the group element. |

### DropdownMenu.GroupHeading

A heading for a group which will be skipped when navigating with the keyboard. It is used to provide a description for a group of menu items and must be a child of either a `DropdownMenu.Group` or `DropdownMenu.RadioGroup` component.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                          | Value         | Description                                                                                              |
| ------------------------------------------------------------------------------------------ | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-menu-group-heading` | `''` | Present on the group heading element. |

### DropdownMenu.Sub

A submenu belonging to the parent dropdown menu. Responsible for managing the state of the submenu.

| Property                                                                                     | Type                                                                                                                                                                                                           | Description                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `open` $bindable | `boolean`                                                                                                                                                           | The open state of the submenu.`Default: false`                                              |
| `onOpenChange`                                             | `function`- (open: boolean) => void | A callback that is fired when the submenu's open state changes.`Default:  undefined`     |
| `children`                                                 | `Snippet`                                                                                                                                                           | The children content to render.`Default:  undefined` |

### DropdownMenu.SubTrigger

A menu item which when pressed or hovered, opens the submenu it is a child of.

| Property                                                                  | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `disabled` | `boolean`                                                                                                                                                                                            | Whether or not the submenu trigger is disabled.`Default: false`                                                                                                                   |
| `textValue`                             | `string`                                                                                                                                                                                             | The text value of the checkbox menu item. This is used for typeahead.`Default:  undefined`                                                                                     |
| `onSelect`                              | `function`- () => void                                               | A callback that is fired when the menu item is selected.`Default:  undefined`                                                                                                  |
| `closeOnSelect`                         | `boolean`                                                                                                                                                                                            | Whether or not the menu item should close when selected.`Default: true`                                                                                                           |
| `ref` $bindable            | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                              | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                 | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                   | Value                                                                                                                                                                                         | Description                                                                                                |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-orientation` | `'vertical'`                                                                                                                                                                         |                                                                                                  |
| `data-highlighted`                                      | `''`                                                                                                                                                                                 | Present when the menu item is highlighted.                                          |
| `data-disabled`                                         | `''`                                                                                                                                                                                 | Present when the menu item is disabled.                                             |
| `data-state`                                            | `enum`- 'open' \| 'closed' | The open state of the menu or submenu the element controls or belongs to.           |
| `data-menu-sub-trigger`                                 | `''`                                                                                                                                                                                 | Present on the submenu trigger element. |

### DropdownMenu.SubContent

The submenu content displayed when the parent submenu is open.

| Property                                                              | Type                                                                                                                                                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `side` | `enum`- 'top' \| 'bottom' \| 'left' \| 'right'                                     | The preferred side of the anchor to render the floating element against when open. Will be reversed when collisions occur.`Default: bottom`                                                                                                                                                                                                                                                                                        |
| `sideOffset`                        | `number`                                                                                                                                                                                                           | The distance in pixels from the anchor to the floating element.`Default: 0`                                                                                                                                                                                                                                                                                                                                                        |
| `align`                             | `enum`- 'start' \| 'center' \| 'end'                                               | The preferred alignment of the anchor to render the floating element against when open. This may change when collisions occur.`Default: start`                                                                                                                                                                                                                                                                                     |
| `alignOffset`                       | `number`                                                                                                                                                                                                           | The distance in pixels from the anchor to the floating element.`Default: 0`                                                                                                                                                                                                                                                                                                                                                        |
| `arrowPadding`                      | `number`                                                                                                                                                                                                           | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0`                                                                                                                                                                                                                                                                                                  |
| `avoidCollisions`                   | `boolean`                                                                                                                                                                                                          | When `true`, overrides the `side` and `align` options to prevent collisions with the boundary edges.`Default: true`                                                                                                                                                                                                                                                                                                                |
| `collisionBoundary`                 | `union`- Element \| null                                                           | A boundary element or array of elements to check for collisions against.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                   |
| `collisionPadding`                  | `union`- number \| Partial\&lt;Record\&lt;Side, number\&gt;\&gt;                   | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0`                                                                                                                                                                                                                                                                                                  |
| `sticky`                            | `enum`- 'partial' \| 'always'                                                      | The sticky behavior on the align axis. `'partial'` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst `'always'` will keep the content in the boundary regardless.`Default: partial`                                                                                                                                                                                        |
| `hideWhenDetached`                  | `boolean`                                                                                                                                                                                                          | When `true`, hides the content when it is detached from the DOM. This is useful for when you want to hide the content when the user scrolls away.`Default: true`                                                                                                                                                                                                                                                                   |
| `updatePositionStrategy`            | `enum`- 'optimized' \| 'always'                                                    | The strategy to use when updating the position of the content. When `'optimized'` the content will only be repositioned when the trigger is in the viewport. When `'always'` the content will be repositioned whenever the position changes.`Default: optimized`                                                                                                                                                                   |
| `strategy`                          | `enum`- 'fixed' \| 'absolute'                                                      | The positioning strategy to use for the floating element. When `'fixed'` the element will be positioned relative to the viewport. When `'absolute'` the element will be positioned relative to the nearest positioned ancestor.`Default: fixed`                                                                                                                                                                                    |
| `preventScroll`                     | `boolean`                                                                                                                                                                                                          | When `true`, prevents the body from scrolling when the content is open. This is useful when you want to use the content as a modal.`Default: true`                                                                                                                                                                                                                                                                                 |
| `customAnchor`                      | `union`- string \| HTMLElement \| Measurable \| null                               | Use an element other than the trigger to anchor the content to. If provided, the content will be anchored to the provided element instead of the trigger.`Default: null`                                                                                                                                                                                                                                                           |
| `onEscapeKeydown`                   | `function`- (event: KeyboardEvent) => void                                         | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default:  undefined`                                                                                                                                                                                                                    |
| `escapeKeydownBehavior`             | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` |
| `onInteractOutside`                 | `function`- (event: PointerEvent) => void                                          | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default:  undefined`                                                                                                                                                                                                        |
| `onFocusOutside`                    | `function`- (event: FocusEvent) => void                                            | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default:  undefined`                                                                                                                                                                                                                                                  |
| `interactOutsideBehavior`           | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close`  |
| `onOpenAutoFocus`                   | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is opened. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `onCloseAutoFocus`                  | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is closed. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `trapFocus`                         | `boolean`                                                                                                                                                                                                          | Whether or not to trap the focus within the content when open.`Default: true`                                                                                                                                                                                                                                                                                                                                                      |
| `forceMount`                        | `boolean`                                                                                                                                                                                                          | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                                                                                                                                                                                                                                                                 |
| `preventOverflowTextSelection`      | `boolean`                                                                                                                                                                                                          | When `true`, prevents the text selection from overflowing the bounds of the element.`Default: true`                                                                                                                                                                                                                                                                                                                                |
| `dir`                               | `enum`- 'ltr' \| 'rtl'                                                             | The reading direction of the app.`Default: 'ltr'`                                                                                                                                                                                                                                                                                                                                                                                  |
| `loop`                              | `boolean`                                                                                                                                                                                                          | Whether or not to loop through the menu items in when navigating with the keyboard.`Default: false`                                                                                                                                                                                                                                                                                                                                |
| `ref` $bindable        | `HTMLDivElement`                                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                                                                                                                                                                         |
| `children`                          | `Snippet`- Snippet                                                                 | The children content to render.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                                                            |
| `child`                             | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };               | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                                                                                                                                                                  | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                                |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | The open state of the menu or submenu the element controls or belongs to.           |
| `data-menu-sub-content`                           | `''`                                                                                                                                                                                 | Present on the submenu content element. |

### DropdownMenu.SubContentStatic

The submenu content displayed when the parent submenu menu is open. (Static/No Floating UI)

| Property                                                                         | Type                                                                                                                                                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onEscapeKeydown` | `function`- (event: KeyboardEvent) => void                                         | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default:  undefined`                                                                                                                                                                                                                    |
| `escapeKeydownBehavior`                        | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` |
| `onInteractOutside`                            | `function`- (event: PointerEvent) => void                                          | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default:  undefined`                                                                                                                                                                                                        |
| `onFocusOutside`                               | `function`- (event: FocusEvent) => void                                            | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default:  undefined`                                                                                                                                                                                                                                                  |
| `interactOutsideBehavior`                      | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close`  |
| `onOpenAutoFocus`                              | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is opened. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `onCloseAutoFocus`                             | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is closed. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `trapFocus`                                    | `boolean`                                                                                                                                                                                                          | Whether or not to trap the focus within the content when open.`Default: true`                                                                                                                                                                                                                                                                                                                                                      |
| `forceMount`                                   | `boolean`                                                                                                                                                                                                          | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                                                                                                                                                                                                                                                                 |
| `preventOverflowTextSelection`                 | `boolean`                                                                                                                                                                                                          | When `true`, prevents the text selection from overflowing the bounds of the element.`Default: true`                                                                                                                                                                                                                                                                                                                                |
| `dir`                                          | `enum`- 'ltr' \| 'rtl'                                                             | The reading direction of the app.`Default: 'ltr'`                                                                                                                                                                                                                                                                                                                                                                                  |
| `loop`                                         | `boolean`                                                                                                                                                                                                          | Whether or not to loop through the menu items when reaching the end of the list when using the keyboard.`Default: true`                                                                                                                                                                                                                                                                                                            |
| `ref` $bindable                   | `HTMLDivElement`                                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                                                                                                                                                                         |
| `children`                                     | `Snippet`- Snippet                                                                 | The children content to render.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                                                            |
| `child`                                        | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };               | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                                                                                                                                                                  | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                                |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | The open state of the menu or submenu the element controls or belongs to.           |
| `data-menu-sub-content`                           | `''`                                                                                                                                                                                 | Present on the submenu content element. |

----------------------------------------------------

# Label Documentation

Identifies or describes associated UI elements.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { Checkbox, Label } from "bits-ui";
  import Check from "phosphor-svelte/lib/Check";
  import Minus from "phosphor-svelte/lib/Minus";
</script>
<div class="flex items-center space-x-3">
  <Checkbox.Root
    id="terms"
    aria-labelledby="terms-label"
    class="border-muted bg-foreground data-[state=unchecked]:border-border-input data-[state=unchecked]:bg-background data-[state=unchecked]:hover:border-dark-40 peer inline-flex size-[25px] items-center justify-center rounded-md border transition-all duration-150 ease-in-out active:scale-[0.98]"
    name="hello"
  >
    {#snippet children({ checked, indeterminate })}
      <div class="text-background inline-flex items-center justify-center">
        {#if indeterminate}
          <Minus class="size-[15px]" weight="bold" />
        {:else if checked}
          <Check class="size-[15px]" weight="bold" />
        {/if}
      </div>
    {/snippet}
  </Checkbox.Root>
  <Label.Root
    id="terms-label"
    for="terms"
    class="text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70"
  >
    Accept terms and conditions
  </Label.Root>
</div>
```

## Structure

```svelte
<script lang="ts">
 import { Label } from "bits-ui";
</script>
<Label.Root />
```

## API Reference

### Label.Root

An enhanced label component that can be used with any input.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLLabelElement`                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                  | Value         | Description                                                                                     |
| ---------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-label-root` | `''` | Present on the root element. |

----------------------------------------------------

# Link Preview Documentation

Displays a summarized preview of a linked content's details or information.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { Avatar, LinkPreview } from "bits-ui";
  import CalendarBlank from "phosphor-svelte/lib/CalendarBlank";
  import MapPin from "phosphor-svelte/lib/MapPin";
  let loadingStatusTrigger: Avatar.RootProps["loadingStatus"] =
    $state("loading");
  let loadingStatusContent: Avatar.RootProps["loadingStatus"] =
    $state("loading");
</script>
<LinkPreview.Root>
  <LinkPreview.Trigger
    href="https://github.com/sveltejs"
    target="_blank"
    rel="noreferrer noopener"
    class="rounded-xs underline-offset-4 hover:underline focus-visible:outline-2 focus-visible:outline-offset-8 focus-visible:outline-black"
  >
    <Avatar.Root
      bind:loadingStatus={loadingStatusTrigger}
      class="h-12 w-12 rounded-full border {loadingStatusTrigger === 'loaded'
        ? 'border-foreground'
        : 'border-transparent'} bg-muted text-muted-foreground text-[17px] font-medium uppercase"
    >
      <div
        class="flex h-full w-full items-center justify-center overflow-hidden rounded-full border-2 border-transparent"
      >
        <Avatar.Image src="/avatar-1.png" alt="@huntabyte" />
        <Avatar.Fallback class="border-muted border">HB</Avatar.Fallback>
      </div>
    </Avatar.Root>
  </LinkPreview.Trigger>
  <LinkPreview.Content
    class="border-muted bg-background shadow-popover w-[331px] rounded-xl border p-[17px]"
    sideOffset={8}
  >
    <div class="flex space-x-4">
      <Avatar.Root
        bind:loadingStatus={loadingStatusContent}
        class="h-12 w-12 rounded-full border {loadingStatusContent === 'loaded'
          ? 'border-foreground'
          : 'border-transparent'} bg-muted text-muted-foreground text-[17px] font-medium uppercase"
      >
        <div
          class="flex h-full w-full items-center justify-center overflow-hidden rounded-full border-2 border-transparent"
        >
          <Avatar.Image src="/avatar-1.png" alt="@huntabyte" />
          <Avatar.Fallback class="border-muted border">HB</Avatar.Fallback>
        </div>
      </Avatar.Root>
      <div class="space-y-1 text-sm">
        <h4 class="font-medium">@huntabyte</h4>
        <p>I do things on the internet.</p>
        <div
          class="text-muted-foreground flex items-center gap-[21px] pt-2 text-xs"
        >
          <div class="flex items-center text-xs">
            <MapPin class="mr-1 size-4" />
            <span> FL, USA </span>
          </div>
          <div class="flex items-center text-xs">
            <CalendarBlank class="mr-1 size-4" />
            <span> Joined May 2020</span>
          </div>
        </div>
      </div>
    </div>
  </LinkPreview.Content>
</LinkPreview.Root>
```

## Overview

A component that lets users preview a link before they decide to follow it. This is useful for providing non-essential context or additional information about a link without having to navigate away from the current page.

##### A note about mobile devices!

This component is only intended to be used with a mouse or other pointing device. It doesn't respond to touch events, and the preview content cannot be accessed via the keyboard. On touch devices, the link will be followed immediately. As it is not accessible to all users, the preview should not contain vital information.

## Structure

```svelte
<script lang="ts">
 import { LinkPreview } from "bits-ui";
</script>
<LinkPreview.Root>
 <LinkPreview.Trigger />
 <LinkPreview.Content />
</LinkPreview.Root>
```

## Managing Open State

This section covers how to manage the `open` state of the component.

### Two-Way Binding

Use `bind:open` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { LinkPreview } from "bits-ui";
 let isOpen = $state(false);
</script>
<button onclick={() => (isOpen = true)}>Open Link Preview</button>
<LinkPreview.Root bind:open={isOpen}>
</LinkPreview.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { LinkPreview } from "bits-ui";
 let myOpen = $state(false);
 function getOpen() {
  return myOpen;
 }
 function setOpen(newOpen: boolean) {
  myOpen = newOpen;
 }
</script>
<LinkPreview.Root bind:open={getOpen, setOpen}>
</LinkPreview.Root>
```

## Opt-out of Floating UI

When you use the `LinkPreview.Content` component, Bits UI uses [Floating UI](https://floating-ui.com/) to position the content relative to the trigger, similar to other popover-like components.

You can opt-out of this behavior by instead using the `LinkPreview.ContentStatic` component. This component does not use Floating UI and leaves positioning the content entirely up to you.

```svelte
<LinkPreview.Root>
 <LinkPreview.Trigger />
 <LinkPreview.ContentStatic>
 </LinkPreview.ContentStatic>
</LinkPreview.Root>
```

##### Heads up!

The `LinkPreview.Arrow` component is designed to be used with Floating UI and `LinkPreview.Content`, so you may experience unexpected behavior if you attempt to use it with `LinkPreview.ContentStatic`.

## Custom Anchor

By default, the `LinkPreview.Content` is anchored to the `LinkPreview.Trigger` component, which determines where the content is positioned.

If you wish to instead anchor the content to a different element, you can pass either a selector `string` or an `HTMLElement` to the `customAnchor` prop of the `LinkPreview.Content` component.

```svelte
<script lang="ts">
 import { LinkPreview } from "bits-ui";
 let customAnchor = $state<HTMLElement>(null!);
</script>
<div bind:this={customAnchor}></div>
<LinkPreview.Root>
 <LinkPreview.Trigger />
 <LinkPreview.Content {customAnchor}>
 </LinkPreview.Content>
</LinkPreview.Root>
```

## Svelte Transitions

You can use the `forceMount` prop along with the `child` snippet to forcefully mount the `LinkPreview.Content` component to use Svelte Transitions or another animation library that requires more control.

```svelte
<script lang="ts">
 import { LinkPreview } from "bits-ui";
 import { fly } from "svelte/transition";
</script>
<LinkPreview.Content forceMount>
 {#snippet child({ wrapperProps, props, open })}
  {#if open}
   <div {...wrapperProps}>
    <div {...props} transition:fly>
    </div>
   </div>
  {/if}
 {/snippet}
</LinkPreview.Content>
```

Of course, this isn't the prettiest syntax, so it's recommended to create your own reusable content component that handles this logic if you intend to use this approach. For more information on using transitions with Bits UI components, see the [Transitions](/docs/transitions) documentation.

```svelte
<script lang="ts">
  import { Avatar, LinkPreview } from "bits-ui";
  import CalendarBlank from "phosphor-svelte/lib/CalendarBlank";
  import MapPin from "phosphor-svelte/lib/MapPin";
  import { fly } from "svelte/transition";
  let loadingStatusTrigger: Avatar.RootProps["loadingStatus"] =
    $state("loading");
  let loadingStatusContent: Avatar.RootProps["loadingStatus"] =
    $state("loading");
</script>
<LinkPreview.Root>
  <LinkPreview.Trigger
    href="https://github.com/sveltejs"
    target="_blank"
    rel="noreferrer noopener"
    class="rounded-xs underline-offset-4 hover:underline focus-visible:outline-2 focus-visible:outline-offset-8 focus-visible:outline-black"
  >
    <Avatar.Root
      bind:loadingStatus={loadingStatusTrigger}
      class="h-12 w-12 rounded-full border {loadingStatusTrigger === 'loaded'
        ? 'border-foreground'
        : 'border-transparent'} bg-muted text-muted-foreground text-[17px] font-medium uppercase"
    >
      <div
        class="flex h-full w-full items-center justify-center overflow-hidden rounded-full border-2 border-transparent"
      >
        <Avatar.Image src="/avatar-1.png" alt="@huntabyte" />
        <Avatar.Fallback class="border-muted border">HB</Avatar.Fallback>
      </div>
    </Avatar.Root>
  </LinkPreview.Trigger>
  <LinkPreview.Content
    class="border-muted bg-background shadow-popover w-[331px] rounded-xl border p-[17px]"
    sideOffset={8}
    forceMount
  >
    {#snippet child({ open, props, wrapperProps })}
      {#if open}
        <div {...wrapperProps}>
          <div {...props} transition:fly={{ duration: 300 }}>
            <div class="flex space-x-4">
              <Avatar.Root
                bind:loadingStatus={loadingStatusContent}
                class="h-12 w-12 rounded-full border {loadingStatusContent ===
                'loaded'
                  ? 'border-foreground'
                  : 'border-transparent'} bg-muted text-muted-foreground text-[17px] font-medium uppercase"
              >
                <div
                  class="flex h-full w-full items-center justify-center overflow-hidden rounded-full border-2 border-transparent"
                >
                  <Avatar.Image src="/avatar-1.png" alt="@huntabyte" />
                  <Avatar.Fallback class="border-muted border"
                    >HB</Avatar.Fallback
                  >
                </div>
              </Avatar.Root>
              <div class="space-y-1 text-sm">
                <h4 class="font-medium">@huntabyte</h4>
                <p>I do things on the internet.</p>
                <div
                  class="text-muted-foreground flex items-center gap-[21px] pt-2 text-xs"
                >
                  <div class="flex items-center text-xs">
                    <MapPin class="mr-1 size-4" />
                    <span> FL, USA </span>
                  </div>
                  <div class="flex items-center text-xs">
                    <CalendarBlank class="mr-1 size-4" />
                    <span> Joined May 2020</span>
                  </div>
                </div>
              </div>
            </div>
          </div>
        </div>
      {/if}
    {/snippet}
  </LinkPreview.Content>
</LinkPreview.Root>
```

## API Reference

### LinkPreview\.Root

The root component used to manage the state of the state of the link preview.

| Property                                                                                     | Type                                                                                                                                                                                                           | Description                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `open` $bindable | `boolean`                                                                                                                                                           | The open state of the link preview component.`Default: false`                                                    |
| `onOpenChange`                                             | `function`- (open: boolean) => void | A callback that fires when the open state changes.`Default:  undefined`                                       |
| `openDelay`                                                | `number`                                                                                                                                                            | The amount of time in milliseconds to delay opening the preview when hovering over the trigger.`Default: 700`    |
| `closeDelay`                                               | `number`                                                                                                                                                            | The amount of time in milliseconds to delay closing the preview when the mouse leaves the trigger.`Default: 300` |
| `disabled`                                                 | `boolean`                                                                                                                                                           | Whether or not the link preview is disabled.`Default: false`                                                     |
| `ignoreNonKeyboardFocus`                                   | `boolean`                                                                                                                                                           | Whether the link preview should ignore non-keyboard focus.`Default: false`                                       |
| `children`                                                 | `Snippet`                                                                                                                                                           | The children content to render.`Default:  undefined`                      |

### LinkPreview\.Trigger

A component which triggers the opening and closing of the link preview on hover or focus.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLAnchorElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                        |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | Whether the accordion item is open or closed.                               |
| `data-link-preview-trigger`                       | `''`                                                                                                                                                                                 | Present on the trigger element. |

### LinkPreview\.Content

The contents of the link preview which are displayed when the preview is open.

| Property                                                              | Type                                                                                                                                                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `side` | `enum`- 'top' \| 'bottom' \| 'left' \| 'right'                                     | The preferred side of the anchor to render the floating element against when open. Will be reversed when collisions occur.`Default: bottom`                                                                                                                                                                                                                                                                                        |
| `sideOffset`                        | `number`                                                                                                                                                                                                           | The distance in pixels from the anchor to the floating element.`Default: 0`                                                                                                                                                                                                                                                                                                                                                        |
| `align`                             | `enum`- 'start' \| 'center' \| 'end'                                               | The preferred alignment of the anchor to render the floating element against when open. This may change when collisions occur.`Default: start`                                                                                                                                                                                                                                                                                     |
| `alignOffset`                       | `number`                                                                                                                                                                                                           | The distance in pixels from the anchor to the floating element.`Default: 0`                                                                                                                                                                                                                                                                                                                                                        |
| `arrowPadding`                      | `number`                                                                                                                                                                                                           | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0`                                                                                                                                                                                                                                                                                                  |
| `avoidCollisions`                   | `boolean`                                                                                                                                                                                                          | When `true`, overrides the `side` and `align` options to prevent collisions with the boundary edges.`Default: true`                                                                                                                                                                                                                                                                                                                |
| `collisionBoundary`                 | `union`- Element \| null                                                           | A boundary element or array of elements to check for collisions against.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                   |
| `collisionPadding`                  | `union`- number \| Partial\&lt;Record\&lt;Side, number\&gt;\&gt;                   | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0`                                                                                                                                                                                                                                                                                                  |
| `sticky`                            | `enum`- 'partial' \| 'always'                                                      | The sticky behavior on the align axis. `'partial'` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst `'always'` will keep the content in the boundary regardless.`Default: partial`                                                                                                                                                                                        |
| `hideWhenDetached`                  | `boolean`                                                                                                                                                                                                          | When `true`, hides the content when it is detached from the DOM. This is useful for when you want to hide the content when the user scrolls away.`Default: true`                                                                                                                                                                                                                                                                   |
| `updatePositionStrategy`            | `enum`- 'optimized' \| 'always'                                                    | The strategy to use when updating the position of the content. When `'optimized'` the content will only be repositioned when the trigger is in the viewport. When `'always'` the content will be repositioned whenever the position changes.`Default: optimized`                                                                                                                                                                   |
| `strategy`                          | `enum`- 'fixed' \| 'absolute'                                                      | The positioning strategy to use for the floating element. When `'fixed'` the element will be positioned relative to the viewport. When `'absolute'` the element will be positioned relative to the nearest positioned ancestor.`Default: fixed`                                                                                                                                                                                    |
| `preventScroll`                     | `boolean`                                                                                                                                                                                                          | When `true`, prevents the body from scrolling when the content is open. This is useful when you want to use the content as a modal.`Default: true`                                                                                                                                                                                                                                                                                 |
| `customAnchor`                      | `union`- string \| HTMLElement \| Measurable \| null                               | Use an element other than the trigger to anchor the content to. If provided, the content will be anchored to the provided element instead of the trigger.`Default: null`                                                                                                                                                                                                                                                           |
| `onInteractOutside`                 | `function`- (event: PointerEvent) => void                                          | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default:  undefined`                                                                                                                                                                                                        |
| `onFocusOutside`                    | `function`- (event: FocusEvent) => void                                            | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default:  undefined`                                                                                                                                                                                                                                                  |
| `interactOutsideBehavior`           | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close`  |
| `onEscapeKeydown`                   | `function`- (event: KeyboardEvent) => void                                         | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default:  undefined`                                                                                                                                                                                                                    |
| `escapeKeydownBehavior`             | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` |
| `onOpenAutoFocus`                   | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is opened. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `onCloseAutoFocus`                  | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is closed. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `trapFocus`                         | `boolean`                                                                                                                                                                                                          | Whether or not to trap the focus within the content when open.`Default: true`                                                                                                                                                                                                                                                                                                                                                      |
| `dir`                               | `enum`- 'ltr' \| 'rtl'                                                             | The reading direction of the app.`Default: 'ltr'`                                                                                                                                                                                                                                                                                                                                                                                  |
| `forceMount`                        | `boolean`                                                                                                                                                                                                          | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                                                                                                                                                                                                                                                                 |
| `ref` $bindable        | `HTMLDivElement`                                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                                                                                                                                                                         |
| `children`                          | `Snippet`                                                                                                                                                                                                          | The children content to render.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                                                            |
| `child`                             | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };               | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                                                                                                                                                                  | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                        |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | Whether the accordion item is open or closed.                               |
| `data-link-preview-content`                       | `''`                                                                                                                                                                                 | Present on the content element. |

| CSS Variable                                                                 | Description                                                                                                        |
| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--bits-link-preview-content-transform-origin` | The transform origin of the link preview content element.                                   |
| `--bits-link-preview-content-available-width`                                       | The available width of the link preview content element.                                    |
| `--bits-link-preview-content-available-height`                                      | The available height of the link preview content element.                                   |
| `--bits-link-preview-anchor-width`                                                  | The width of the link preview trigger element.                                              |
| `--bits-link-preview-anchor-height`                                                 | The height of the link preview trigger element. |

### LinkPreview\.ContentStatic

The contents of the link preview which are displayed when the preview is open. (Static/No Floating UI)

| Property                                                                           | Type                                                                                                                                                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onInteractOutside` | `function`- (event: PointerEvent) => void                                          | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default:  undefined`                                                                                                                                                                                                        |
| `onFocusOutside`                                 | `function`- (event: FocusEvent) => void                                            | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default:  undefined`                                                                                                                                                                                                                                                  |
| `interactOutsideBehavior`                        | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close`  |
| `onEscapeKeydown`                                | `function`- (event: KeyboardEvent) => void                                         | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default:  undefined`                                                                                                                                                                                                                    |
| `escapeKeydownBehavior`                          | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` |
| `onOpenAutoFocus`                                | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is opened. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `onCloseAutoFocus`                               | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is closed. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `trapFocus`                                      | `boolean`                                                                                                                                                                                                          | Whether or not to trap the focus within the content when open.`Default: true`                                                                                                                                                                                                                                                                                                                                                      |
| `dir`                                            | `enum`- 'ltr' \| 'rtl'                                                             | The reading direction of the app.`Default: 'ltr'`                                                                                                                                                                                                                                                                                                                                                                                  |
| `forceMount`                                     | `boolean`                                                                                                                                                                                                          | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                                                                                                                                                                                                                                                                 |
| `ref` $bindable                     | `HTMLDivElement`                                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                                                                                                                                                                         |
| `children`                                       | `Snippet`                                                                                                                                                                                                          | The children content to render.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                                                            |
| `child`                                          | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };               | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                                                                                                                                                                  | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                        |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | Whether the accordion item is open or closed.                               |
| `data-link-preview-content`                       | `''`                                                                                                                                                                                 | Present on the content element. |

### LinkPreview\.Arrow

An optional arrow element which points to the trigger when the preview is open.

| Property                                                               | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `width` | `number`                                                                                                                                                                                             | The width of the arrow in pixels.`Default: 8`                                                                                                                                     |
| `height`                             | `number`                                                                                                                                                                                             | The height of the arrow in pixels.`Default: 8`                                                                                                                                    |
| `ref` $bindable         | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                           | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                              | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                          | Value         | Description                                                                                      |
| ------------------------------------------------------------------------------------------ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-link-preview-arrow` | `''` | Present on the arrow element. |

----------------------------------------------------

# Menubar Documentation

Organizes and presents a collection of menu options or actions within a horizontal bar.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { Menubar } from "bits-ui";
  import CaretRight from "phosphor-svelte/lib/CaretRight";
  import Cat from "phosphor-svelte/lib/Cat";
  import Check from "phosphor-svelte/lib/Check";
  let selectedView = $state("table");
  let selectedProfile = $state("pavel");
  let grids = $state([
    {
      checked: true,
      label: "Pixel"
    },
    {
      checked: false,
      label: "Layout"
    }
  ]);
  let showConfigs = $state([
    {
      checked: true,
      label: "Show Bookmarks"
    },
    {
      checked: false,
      label: "Show Full URLs"
    }
  ]);
  const profiles = [
    {
      value: "hunter",
      label: "Hunter"
    },
    {
      value: "pavel",
      label: "Pavel"
    },
    {
      value: "adrian",
      label: "Adrian"
    }
  ];
  const views = [
    {
      value: "table",
      label: "Table"
    },
    {
      value: "board",
      label: "Board"
    },
    {
      value: "gallery",
      label: "Gallery"
    }
  ];
</script>
<Menubar.Root
  class="rounded-10px border-dark-10 bg-background-alt shadow-mini flex h-12 items-center gap-1 border px-[3px]"
>
  <div class="px-2.5">
    <Cat class="size-6" />
  </div>
  <Menubar.Menu>
    <Menubar.Trigger
      id="file"
      class="rounded-9px data-highlighted:bg-muted data-[state=open]:bg-muted ring-0! ring-transparent! inline-flex h-10 cursor-default items-center justify-center px-3 text-sm font-medium"
    >
      File
    </Menubar.Trigger>
    <Menubar.Portal>
      <Menubar.Content
        class="focus-override border-muted bg-background  shadow-popover focus-visible:outline-hidden z-50 w-fit rounded-xl border px-1 py-1.5"
        align="start"
        sideOffset={3}
      >
        {#each grids as grid}
          <Menubar.CheckboxItem
            class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center gap-3 py-3 pl-3 pr-1.5 text-sm font-medium"
            bind:checked={grid.checked}
          >
            {#snippet children({ checked })}
              {grid.label} grid
              <div class="ml-auto flex items-center">
                {#if checked}
                  <SwitchOn />
                {:else}
                  <SwitchOff />
                {/if}
              </div>
            {/snippet}
          </Menubar.CheckboxItem>
        {/each}
        <Menubar.Separator class="bg-muted my-1 -ml-1 -mr-1 block h-px" />
        <Menubar.RadioGroup bind:value={selectedView}>
          {#each views as view}
            <Menubar.RadioItem
              value={view.value}
              class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center gap-2 py-3 pl-3 pr-1.5 text-sm font-medium"
            >
              {#snippet children({ checked })}
                {view.label}
                <div class="ml-auto size-5">
                  {#if checked}
                    <Check class="size-5" />
                  {/if}
                </div>
              {/snippet}
            </Menubar.RadioItem>
          {/each}
        </Menubar.RadioGroup>
      </Menubar.Content>
    </Menubar.Portal>
  </Menubar.Menu>
  <Menubar.Menu>
    <Menubar.Trigger
      id="edit"
      class="data-highlighted:bg-muted data-[state=open]:bg-muted ring-0! ring-transparent! inline-flex h-10 cursor-default items-center justify-center rounded-[9px] px-3 text-sm font-medium"
    >
      Edit
    </Menubar.Trigger>
    <Menubar.Portal>
      <Menubar.Content
        class="focus-override border-muted bg-background shadow-popover focus-visible:outline-hidden z-50 w-full rounded-xl border px-1 py-1.5"
        align="start"
        sideOffset={3}
      >
        <Menubar.Item
          class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
        >
          Undo
        </Menubar.Item>
        <Menubar.Item
          class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 min-w-[130px] select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
        >
          Redo
        </Menubar.Item>
        <Menubar.Separator />
        <Menubar.Sub>
          <Menubar.SubTrigger
            class="rounded-button data-highlighted:bg-muted data-[state=open]:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center gap-3 py-3 pl-3 pr-1.5 text-sm font-medium"
          >
            Find
            <div class="ml-auto flex items-center">
              <CaretRight class="text-foreground-alt h-4 w-4" />
            </div>
          </Menubar.SubTrigger>
          <Menubar.SubContent
            class="focus-override border-muted bg-background shadow-popover focus-visible:outline-hidden w-full max-w-[209px] rounded-xl border px-1 py-1.5"
          >
            <Menubar.Item
              class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
            >
              Search the web
            </Menubar.Item>
            <Menubar.Separator />
            <Menubar.Item
              class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
            >
              Find...
            </Menubar.Item>
            <Menubar.Item
              class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
            >
              Find Next
            </Menubar.Item>
            <Menubar.Item
              class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
            >
              Find Previous
            </Menubar.Item>
          </Menubar.SubContent>
        </Menubar.Sub>
        <Menubar.Separator />
        <Menubar.Item
          class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
        >
          Cut
        </Menubar.Item>
        <Menubar.Item
          class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
        >
          Copy
        </Menubar.Item>
        <Menubar.Item
          class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
        >
          Paste
        </Menubar.Item>
      </Menubar.Content>
    </Menubar.Portal>
  </Menubar.Menu>
  <Menubar.Menu>
    <Menubar.Trigger
      id="view"
      class="rounded-9px data-highlighted:bg-muted data-[state=open]:bg-muted ring-0! ring-transparent! inline-flex h-10 cursor-default items-center justify-center px-3 text-sm font-medium"
    >
      View
    </Menubar.Trigger>
    <Menubar.Portal>
      <Menubar.Content
        class="focus-override border-muted bg-background shadow-popover focus-visible:outline-hidden z-50 w-full max-w-[220px] rounded-xl border px-1 py-1.5"
        align="start"
        sideOffset={3}
      >
        {#each showConfigs as config}
          <Menubar.CheckboxItem
            class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center gap-3 py-3 pl-3 pr-1.5 text-sm font-medium"
            bind:checked={config.checked}
          >
            {#snippet children({ checked })}
              {config.label}
              <div class="ml-auto flex items-center">
                {#if checked}
                  {@render SwitchOn()}
                {:else}
                  {@render SwitchOff()}
                {/if}
              </div>
            {/snippet}
          </Menubar.CheckboxItem>
        {/each}
        <Menubar.Separator />
        <Menubar.Item
          class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
        >
          Reload
        </Menubar.Item>
        <Menubar.Item
          class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
        >
          Force Reload
        </Menubar.Item>
        <Menubar.Separator />
        <Menubar.Item
          class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
        >
          Toggle Fullscreen
        </Menubar.Item>
        <Menubar.Separator />
        <Menubar.Item
          class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
        >
          Hide Sidebar
        </Menubar.Item>
      </Menubar.Content>
    </Menubar.Portal>
  </Menubar.Menu>
  <Menubar.Menu>
    <Menubar.Trigger
      id="profiles"
      class="data-highlighted:bg-muted data-[state=open]:bg-muted ring-0! ring-transparent! mr-[20px] inline-flex h-10 cursor-default items-center justify-center rounded-[9px] px-3 text-sm font-medium"
    >
      Profiles
    </Menubar.Trigger>
    <Menubar.Portal>
      <Menubar.Content
        class="focus-override border-muted bg-background shadow-popover focus-visible:outline-hidden z-50 w-full max-w-[220px] rounded-xl border px-1 py-1.5"
        align="start"
        sideOffset={3}
      >
        <Menubar.RadioGroup bind:value={selectedProfile}>
          {#each profiles as profile}
            <Menubar.RadioItem
              class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
              value={profile.value}
            >
              {#snippet children({ checked })}
                {profile.label}
                <div class="ml-auto flex items-center">
                  {#if checked}
                    <Check class="size-5" />
                  {/if}
                </div>
              {/snippet}
            </Menubar.RadioItem>
          {/each}
        </Menubar.RadioGroup>
        <Menubar.Separator />
        <Menubar.Item
          class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
          >Edit...</Menubar.Item
        >
        <Menubar.Separator />
        <Menubar.Item
          class="rounded-button data-highlighted:bg-muted ring-0! ring-transparent! flex h-10 select-none items-center py-3 pl-3 pr-1.5 text-sm font-medium"
          >Add Profile...</Menubar.Item
        >
      </Menubar.Content>
    </Menubar.Portal>
  </Menubar.Menu>
</Menubar.Root>
{#snippet SwitchOn()}
  <div
    class="bg-dark-10 peer inline-flex h-[15.6px] min-h-[15.6px] w-[26px] shrink-0 items-center rounded-full px-[1.5px]"
  >
    <span
      class="bg-background dark:border-border-input dark:shadow-mini pointer-events-none block size-[13px] shrink-0 translate-x-[10px] rounded-full"
    ></span>
  </div>
{/snippet}
{#snippet SwitchOff()}
  <div
    class="bg-dark-10 shadow-mini-inset peer inline-flex h-[15.6px] w-[26px] shrink-0 items-center rounded-full px-[3px] transition-colors"
  >
    <span
      class="bg-background shadow-mini dark:border-border-input dark:shadow-mini pointer-events-none block size-[13px] shrink-0 translate-x-0 rounded-full transition-transform dark:border"
    ></span>
  </div>
{/snippet}
```

## Structure

```svelte
<script lang="ts">
 import { Menubar } from "bits-ui";
</script>
<Menubar.Root>
 <Menubar.Menu>
  <Menubar.Trigger />
  <Menubar.Portal>
   <Menubar.Content>
    <Menubar.Group>
     <Menubar.GroupHeading />
     <Menubar.Item />
    </Menubar.Group>
    <Menubar.Item />
    <Menubar.CheckboxItem>
     {#snippet children({ checked })}
      {checked ? "" : ""}
     {/snippet}
    </Menubar.CheckboxItem>
    <Menubar.RadioGroup>
     <Menubar.GroupHeading />
     <Menubar.RadioItem>
      {#snippet children({ checked })}
       {checked ? "" : ""}
      {/snippet}
     </Menubar.RadioItem>
    </Menubar.RadioGroup>
    <Menubar.Sub>
     <Menubar.SubTrigger />
     <Menubar.SubContent />
    </Menubar.Sub>
    <Menubar.Separator />
    <Menubar.Arrow />
   </Menubar.Content>
  </Menubar.Portal>
 </Menubar.Menu>
</Menubar.Root>
```

## Reusable Components

If you're planning to use Menubar in multiple places, you can create reusable components that wrap the different parts of the Menubar.

In the following example, we're creating a reusable `MyMenubarMenu` component that contains the trigger, content, and items of a menu.

MyMenubarMenu.svelte

```svelte
<script lang="ts">
 import { Menubar, type WithoutChildrenOrChild } from "bits-ui";
 type Props = WithoutChildrenOrChild<Menubar.MenuProps> & {
  triggerText: string;
  items: { label: string; value: string; onSelect?: () => void }[];
  contentProps?: WithoutChildrenOrChild<Menubar.ContentProps>;
  // other component props if needed
 };
 let { triggerText, items, contentProps, ...restProps }: Props = $props();
</script>
<Menubar.Menu {...restProps}>
 <Menubar.Trigger>
  {triggerText}
 </Menubar.Trigger>
 <Menubar.Content {...contentProps}>
  <Menubar.Group aria-label={triggerText}>
   {#each items as item}
    <Menubar.Item textValue={item.label} onSelect={item.onSelect}>
     {item.label}
    </Menubar.Item>
   {/each}
  </Menubar.Group>
 </Menubar.Content>
</Menubar.Menu>
```

Now, we can use the `MyMenubarMenu` component within a `Menubar.Root` component to render out the various menus.

```svelte
<script lang="ts">
 import { Menubar } from "bits-ui";
 import MyMenubarMenu from "./MyMenubarMenu.svelte";
 const sales = [
  { label: "Michael Scott", value: "michael" },
  { label: "Dwight Schrute", value: "dwight" },
  { label: "Jim Halpert", value: "jim" },
  { label: "Stanley Hudson", value: "stanley" },
  { label: "Phyllis Vance", value: "phyllis" },
  { label: "Pam Beesly", value: "pam" },
  { label: "Andy Bernard", value: "andy" },
 ];
 const hr = [
  { label: "Toby Flenderson", value: "toby" },
  { label: "Holly Flax", value: "holly" },
  { label: "Jan Levinson", value: "jan" },
 ];
 const accounting = [
  { label: "Angela Martin", value: "angela" },
  { label: "Kevin Malone", value: "kevin" },
  { label: "Oscar Martinez", value: "oscar" },
 ];
 const menubarMenus = [
  { title: "Sales", items: sales },
  { title: "HR", items: hr },
  { title: "Accounting", items: accounting },
 ];
</script>
<Menubar.Root>
 {#each menubarMenus as { title, items }}
  <CustomMenubar triggerText={title} {items} />
 {/each}
</Menubar.Root>
```

## Managing Value State

This section covers how to manage the `value` state of the menubar.

### Two-Way Binding

Use `bind:value` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { Menubar } from "bits-ui";
 let activeValue = $state("");
</script>
<button onclick={() => (activeValue = "menu-1")}>Open Menubar Menu</button>
<Menubar.Root bind:value={activeValue}>
 <Menubar.Menu value="menu-1">
 </Menubar.Menu>
 <Menubar.Menu value="menu-2">
 </Menubar.Menu>
</Menubar.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { Menubar } from "bits-ui";
 let activeValue = $state("");
 function getValue() {
  return activeValue;
 }
 function setValue(newValue: string) {
  activeValue = newValue;
 }
</script>
<Menubar.Root bind:value={getValue, setValue}>
 <Menubar.Menu value="menu-1">
 </Menubar.Menu>
 <Menubar.Menu value="menu-2">
 </Menubar.Menu>
</Menubar.Root>
```

## Checkbox Items

You can use the `Menubar.CheckboxItem` component to create a `menuitemcheckbox` element to add checkbox functionality to menu items.

```svelte
<script lang="ts">
 import { Menubar } from "bits-ui";
 let notifications = $state(true);
</script>
<Menubar.CheckboxItem bind:checked={notifications}>
 {#snippet children({ checked, indeterminate })}
  {#if indeterminate}
   -
  {:else if checked}
   
  {/if}
  Notifications
 {/snippet}
</Menubar.CheckboxItem>
```

## Radio Groups

You can combine the `Menubar.RadioGroup` and `Menubar.RadioItem` components to create a radio group within a menu.

```svelte
<script lang="ts">
 import { Menubar } from "bits-ui";
 const values = ["one", "two", "three"];
 let value = $state("one");
</script>
<Menubar.RadioGroup bind:value>
 {#each values as value}
  <Menubar.RadioItem {value}>
   {#snippet children({ checked })}
    {#if checked}
     
    {/if}
    {value}
   {/snippet}
  </Menubar.RadioItem>
 {/each}
</Menubar.RadioGroup>
```

## Nested Menus

You can create nested menus using the `Menubar.Sub` component to create complex menu structures.

```svelte
<script lang="ts">
 import { Menubar } from "bits-ui";
</script>
<Menubar.Content>
 <Menubar.Item>Item 1</Menubar.Item>
 <Menubar.Item>Item 2</Menubar.Item>
 <Menubar.Sub>
  <Menubar.SubTrigger>Open Sub Menu</Menubar.SubTrigger>
  <Menubar.SubContent>
   <Menubar.Item>Sub Item 1</Menubar.Item>
   <Menubar.Item>Sub Item 2</Menubar.Item>
  </Menubar.SubContent>
 </Menubar.Sub>
</Menubar.Content>
```

## Svelte Transitions

You can use the `forceMount` prop along with the `child` snippet to forcefully mount the `Menubar.Content` component to use Svelte Transitions or another animation library that requires more control.

```svelte
<script lang="ts">
 import { Menubar } from "bits-ui";
 import { fly } from "svelte/transition";
</script>
<Menubar.Content forceMount>
 {#snippet child({ wrapperProps, props, open })}
  {#if open}
   <div {...wrapperProps}>
    <div {...props} transition:fly>
     <Menubar.Item>Item 1</Menubar.Item>
     <Menubar.Item>Item 2</Menubar.Item>
    </div>
   </div>
  {/if}
 {/snippet}
</Menubar.Content>
```

Of course, this isn't the prettiest syntax, so it's recommended to create your own reusable content component that handles this logic if you intend to use this approach. For more information on using transitions with Bits UI components, see the [Transitions](/docs/transitions) documentation.

## API Reference

### Menubar.Root

The root menubar component which manages & scopes the state of the menubar.

| Property                                                                                      | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` $bindable | `string`                                                                                                                                                                                             | The value of the currently active menu.`Default:  undefined`                                                                                                                   |
| `onValueChange`                                             | `function`- (value: string) => void                                  | A callback function called when the active menu value changes.`Default:  undefined`                                                                                            |
| `dir`                                                       | `enum`- 'ltr' \| 'rtl'                                               | The reading direction of the app.`Default: 'ltr'`                                                                                                                                 |
| `loop`                                                      | `boolean`                                                                                                                                                                                            | Whether or not to loop through the menubar menu triggers when navigating with the keyboard.`Default: true`                                                                        |
| `ref` $bindable                                | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                  | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                     | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | ### Menubar.Menu

A menu within the menubar.

| Property                                                               | Type                                                                                                                                                                                                           | Description                                                                                                                                                 |
| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` | `string`                                                                                                                                                            | The value of this menu within the menubar, used to identify it when determining which menu is active.`Default:  undefined` |
| `open` $bindable        | `boolean`                                                                                                                                                           | The open state of the menu.`Default: false`                                                                                   |
| `onOpenChange`                       | `function`- (open: boolean) => void | A callback that is fired when the menu's open state changes.`Default:  undefined`                                          |
| `dir`                                | `enum`- 'ltr' \| 'rtl'              | The reading direction of the app.`Default: 'ltr'`                                                                             |
| `children`                           | `Snippet`                                                                                                                                                           | The children content to render.`Default:  undefined`                                   |

### Menubar.Trigger

The button element which toggles the dropdown menu.

| Property                                                                  | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `disabled` | `boolean`                                                                                                                                                                                            | Whether or not the menu trigger is disabled.`Default: false`                                                                                                                      |
| `ref` $bindable            | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                              | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                 | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                        |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | The open state of the menu or submenu the element controls or belongs to.   |
| `data-menu-trigger`                               | `''`                                                                                                                                                                                 | Present on the trigger element. |

### Menubar.Portal

A component that portals the content of the dropdown menu to the body or a custom target (if provided).

| Property                                                            | Type                                                                                                                                                                                                                           | Description                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `to` | `union`- string \| HTMLElement \| null \| undefined | Where to render the content when it is open. Defaults to the body. Can be disabled by passing `null``Default: body`              |
| `disabled`                        | `boolean`                                                                                                                                                                           | Whether the portal is disabled or not. When disabled, the content will be rendered in its original DOM location.`Default: false` |
| `children`                        | `Snippet`                                                                                                                                                                           | The children content to render.`Default:  undefined`                                      |

### Menubar.Content

The content displayed when the dropdown menu is open.

| Property                                                              | Type                                                                                                                                                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `side` | `enum`- 'top' \| 'bottom' \| 'left' \| 'right'                                     | The preferred side of the anchor to render the floating element against when open. Will be reversed when collisions occur.`Default: bottom`                                                                                                                                                                                                                                                                                        |
| `sideOffset`                        | `number`                                                                                                                                                                                                           | The distance in pixels from the anchor to the floating element.`Default: 0`                                                                                                                                                                                                                                                                                                                                                        |
| `align`                             | `enum`- 'start' \| 'center' \| 'end'                                               | The preferred alignment of the anchor to render the floating element against when open. This may change when collisions occur.`Default: start`                                                                                                                                                                                                                                                                                     |
| `alignOffset`                       | `number`                                                                                                                                                                                                           | The distance in pixels from the anchor to the floating element.`Default: 0`                                                                                                                                                                                                                                                                                                                                                        |
| `arrowPadding`                      | `number`                                                                                                                                                                                                           | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0`                                                                                                                                                                                                                                                                                                  |
| `avoidCollisions`                   | `boolean`                                                                                                                                                                                                          | When `true`, overrides the `side` and `align` options to prevent collisions with the boundary edges.`Default: true`                                                                                                                                                                                                                                                                                                                |
| `collisionBoundary`                 | `union`- Element \| null                                                           | A boundary element or array of elements to check for collisions against.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                   |
| `collisionPadding`                  | `union`- number \| Partial\&lt;Record\&lt;Side, number\&gt;\&gt;                   | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0`                                                                                                                                                                                                                                                                                                  |
| `sticky`                            | `enum`- 'partial' \| 'always'                                                      | The sticky behavior on the align axis. `'partial'` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst `'always'` will keep the content in the boundary regardless.`Default: partial`                                                                                                                                                                                        |
| `hideWhenDetached`                  | `boolean`                                                                                                                                                                                                          | When `true`, hides the content when it is detached from the DOM. This is useful for when you want to hide the content when the user scrolls away.`Default: true`                                                                                                                                                                                                                                                                   |
| `updatePositionStrategy`            | `enum`- 'optimized' \| 'always'                                                    | The strategy to use when updating the position of the content. When `'optimized'` the content will only be repositioned when the trigger is in the viewport. When `'always'` the content will be repositioned whenever the position changes.`Default: optimized`                                                                                                                                                                   |
| `strategy`                          | `enum`- 'fixed' \| 'absolute'                                                      | The positioning strategy to use for the floating element. When `'fixed'` the element will be positioned relative to the viewport. When `'absolute'` the element will be positioned relative to the nearest positioned ancestor.`Default: fixed`                                                                                                                                                                                    |
| `preventScroll`                     | `boolean`                                                                                                                                                                                                          | When `true`, prevents the body from scrolling when the content is open. This is useful when you want to use the content as a modal.`Default: true`                                                                                                                                                                                                                                                                                 |
| `customAnchor`                      | `union`- string \| HTMLElement \| Measurable \| null                               | Use an element other than the trigger to anchor the content to. If provided, the content will be anchored to the provided element instead of the trigger.`Default: null`                                                                                                                                                                                                                                                           |
| `onEscapeKeydown`                   | `function`- (event: KeyboardEvent) => void                                         | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default:  undefined`                                                                                                                                                                                                                    |
| `escapeKeydownBehavior`             | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` |
| `onInteractOutside`                 | `function`- (event: PointerEvent) => void                                          | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default:  undefined`                                                                                                                                                                                                        |
| `onFocusOutside`                    | `function`- (event: FocusEvent) => void                                            | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default:  undefined`                                                                                                                                                                                                                                                  |
| `interactOutsideBehavior`           | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close`  |
| `onOpenAutoFocus`                   | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is opened. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `onCloseAutoFocus`                  | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is closed. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `trapFocus`                         | `boolean`                                                                                                                                                                                                          | Whether or not to trap the focus within the content when open.`Default: true`                                                                                                                                                                                                                                                                                                                                                      |
| `forceMount`                        | `boolean`                                                                                                                                                                                                          | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                                                                                                                                                                                                                                                                 |
| `preventOverflowTextSelection`      | `boolean`                                                                                                                                                                                                          | When `true`, prevents the text selection from overflowing the bounds of the element.`Default: true`                                                                                                                                                                                                                                                                                                                                |
| `dir`                               | `enum`- 'ltr' \| 'rtl'                                                             | The reading direction of the app.`Default: 'ltr'`                                                                                                                                                                                                                                                                                                                                                                                  |
| `loop`                              | `boolean`                                                                                                                                                                                                          | Whether or not to loop through the menu items in when navigating with the keyboard.`Default: false`                                                                                                                                                                                                                                                                                                                                |
| `ref` $bindable        | `HTMLDivElement`                                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                                                                                                                                                                         |
| `children`                          | `Snippet`- Snippet                                                                 | The children content to render.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                                                            |
| `child`                             | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };               | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                                                                                                                                                                  | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                        |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | The open state of the menu or submenu the element controls or belongs to.   |
| `data-menu-content`                               | `''`                                                                                                                                                                                 | Present on the content element. |

| CSS Variable                                                                 | Description                                                                                                         |
| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--bits-menubar-menu-content-transform-origin` | The transform origin of the dropdown menu content element.                                   |
| `--bits-menubar-menu-content-available-width`                                       | The available width of the dropdown menu content element.                                    |
| `--bits-menubar-menu-content-available-height`                                      | The available height of the dropdown menu content element.                                   |
| `--bits-menubar-menu-anchor-width`                                                  | The width of the dropdown menu trigger element.                                              |
| `--bits-menubar-menu-anchor-height`                                                 | The height of the dropdown menu trigger element. |

### Menubar.Item

A menu item within the dropdown menu.

| Property                                                                  | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `disabled` | `boolean`                                                                                                                                                                                            | Whether or not the menu item is disabled.`Default: false`                                                                                                                         |
| `textValue`                             | `string`                                                                                                                                                                                             | The text value of the checkbox menu item. This is used for typeahead.`Default:  undefined`                                                                                     |
| `onSelect`                              | `function`- () => void                                               | A callback that is fired when the menu item is selected.`Default:  undefined`                                                                                                  |
| `closeOnSelect`                         | `boolean`                                                                                                                                                                                            | Whether or not the menu item should close when selected.`Default: true`                                                                                                           |
| `ref` $bindable            | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                              | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                 | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                   | Value                 | Description                                                                                     |
| ----------------------------------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-orientation` | `'vertical'` |                                                                                       |
| `data-highlighted`                                      | `''`         | Present when the menu item is highlighted.                               |
| `data-disabled`                                         | `''`         | Present when the menu item is disabled.                                  |
| `data-menu-item`                                        | `''`         | Present on the item element. |

### Menubar.CheckboxItem

A menu item that can be controlled and toggled like a checkbox.

| Property                                                                  | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `disabled` | `boolean`                                                                                                                                                                                            | Whether or not the checkbox menu item is disabled. Disabled items cannot be interacted with and are skipped when navigating with the keyboard.`Default: false`                    |
| `checked` $bindable        | `boolean`                                                                                                                                                                                            | The checkbox menu item's checked state.`Default: false`                                                                                                                           |
| `onCheckedChange`                       | `function`- (checked: boolean) => void                               | A callback that is fired when the checkbox menu item's checked state changes.`Default:  undefined`                                                                             |
| `indeterminate` $bindable  | `boolean`                                                                                                                                                                                            | Whether the checkbox menu item is in an indeterminate state or not.`Default: false`                                                                                               |
| `onIndeterminateChange`                 | `function`- (indeterminate: boolean) => void                         | A callback that is fired when the indeterminate state changes.`Default:  undefined`                                                                                            |
| `textValue`                             | `string`                                                                                                                                                                                             | The text value of the checkbox menu item. This is used for typeahead.`Default:  undefined`                                                                                     |
| `onSelect`                              | `function`- () => void                                               | A callback that is fired when the menu item is selected.`Default:  undefined`                                                                                                  |
| `closeOnSelect`                         | `boolean`                                                                                                                                                                                            | Whether or not the menu item should close when selected.`Default: true`                                                                                                           |
| `ref` $bindable            | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                              | `Snippet`- Snippet                                                   | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                 | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                   | Value                                                                                                                                                                         | Description                                                                                                |
| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-orientation` | `'vertical'`                                                                                                                                                         |                                                                                                  |
| `data-highlighted`                                      | `''`                                                                                                                                                                 | Present when the menu item is highlighted.                                          |
| `data-disabled`                                         | `''`                                                                                                                                                                 | Present when the menu item is disabled.                                             |
| `data-state`                                            | `enum`- '' | The checkbox menu item's checked state. | ### Menubar.RadioGroup

A group of radio menu items, where only one can be checked at a time.

| Property                                                                                      | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` $bindable | `string`                                                                                                                                                                                             | The value of the currently checked radio menu item.`Default:  undefined`                                                                                                       |
| `onValueChange`                                             | `function`- (value: string) => void                                  | A callback that is fired when the radio group's value changes.`Default:  undefined`                                                                                            |
| `ref` $bindable                                | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                  | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                     | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                        | Value         | Description                                                                                            |
| ---------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-menu-radio-group` | `''` | Present on the radio group element. |

### Menubar.RadioItem

A menu item that can be controlled and toggled like a radio button. It must be a child of a `RadioGroup`.

| Property                                                                                     | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` required | `string`                                                                                                                                                                                             | The value of the radio item. When checked, the parent `RadioGroup`'s value will be set to this value.`Default:  undefined`                                                     |
| `disabled`                                                 | `boolean`                                                                                                                                                                                            | Whether or not the radio menu item is disabled. Disabled items cannot be interacted with and are skipped when navigating with the keyboard.`Default: false`                       |
| `textValue`                                                | `string`                                                                                                                                                                                             | The text value of the checkbox menu item. This is used for typeahead.`Default:  undefined`                                                                                     |
| `onSelect`                                                 | `function`- () => void                                               | A callback that is fired when the menu item is selected.`Default:  undefined`                                                                                                  |
| `closeOnSelect`                                            | `boolean`                                                                                                                                                                                            | Whether or not the menu item should close when selected.`Default: true`                                                                                                           |
| `ref` $bindable                               | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                 | `Snippet`- Snippet                                                   | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                    | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                   | Value                                                                                                                                                                         | Description                                                                                           |
| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-orientation` | `'vertical'`                                                                                                                                                         |                                                                                             |
| `data-highlighted`                                      | `''`                                                                                                                                                                 | Present when the menu item is highlighted.                                     |
| `data-disabled`                                         | `''`                                                                                                                                                                 | Present when the menu item is disabled.                                        |
| `data-state`                                            | `enum`- '' | The radio menu item's checked state.                                           |
| `data-value`                                            | `''`                                                                                                                                                                 | The value of the radio item.                                                   |
| `data-menu-radio-item`                                  | `''`                                                                                                                                                                 | Present on the radio item element. |

### Menubar.Separator

A horizontal line to visually separate menu items.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                   | Value                 | Description                                                                                          |
| ----------------------------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-orientation` | `'vertical'` | The orientation of the separator.                                             |
| `data-menu-separator`                                   | `''`         | Present on the separator element. |

### Menubar.Arrow

An optional arrow which points to the dropdown menu's anchor/trigger point.

| Property                                                               | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `width` | `number`                                                                                                                                                                                             | The width of the arrow in pixels.`Default: 8`                                                                                                                                     |
| `height`                             | `number`                                                                                                                                                                                             | The height of the arrow in pixels.`Default: 8`                                                                                                                                    |
| `ref` $bindable         | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                           | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                              | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                      |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-state` | `enum`- 'open' \| 'closed' | The open state of the menu or submenu the element controls or belongs to. |
| `data-menu-arrow`                                 | `''`                                                                                                                                                                                 | Present on the arrow element. |

### Menubar.Group

A group of menu items. It should be passed an `aria-label` or have a child `Menu.GroupHeading` component to provide a label for a group of menu items.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                  | Value         | Description                                                                                      |
| ---------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-menu-group` | `''` | Present on the group element. |

### Menubar.GroupHeading

A heading for a group which will be skipped when navigating with the keyboard. It is used to provide a heading for a group of menu items and must be a child of either a `Menubar.Group` or `Menubar.RadioGroup` component.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                          | Value         | Description                                                                                              |
| ------------------------------------------------------------------------------------------ | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-menu-group-heading` | `''` | Present on the group heading element. |

### Menubar.Sub

A submenu belonging to the parent dropdown menu. Responsible for managing the state of the submenu.

| Property                                                                                     | Type                                                                                                                                                                                                           | Description                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `open` $bindable | `boolean`                                                                                                                                                           | The open state of the submenu.`Default: false`                                              |
| `onOpenChange`                                             | `function`- (open: boolean) => void | A callback that is fired when the submenu's open state changes.`Default:  undefined`     |
| `children`                                                 | `Snippet`                                                                                                                                                           | The children content to render.`Default:  undefined` |

### Menubar.SubTrigger

A menu item which when pressed or hovered, opens the submenu it is a child of.

| Property                                                                  | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `disabled` | `boolean`                                                                                                                                                                                            | Whether or not the submenu trigger is disabled.`Default: false`                                                                                                                   |
| `textValue`                             | `string`                                                                                                                                                                                             | The text value of the checkbox menu item. This is used for typeahead.`Default:  undefined`                                                                                     |
| `onSelect`                              | `function`- () => void                                               | A callback that is fired when the menu item is selected.`Default:  undefined`                                                                                                  |
| `closeOnSelect`                         | `boolean`                                                                                                                                                                                            | Whether or not the menu item should close when selected.`Default: true`                                                                                                           |
| `ref` $bindable            | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                              | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                 | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                   | Value                                                                                                                                                                                         | Description                                                                                                |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-orientation` | `'vertical'`                                                                                                                                                                         |                                                                                                  |
| `data-highlighted`                                      | `''`                                                                                                                                                                                 | Present when the menu item is highlighted.                                          |
| `data-disabled`                                         | `''`                                                                                                                                                                                 | Present when the menu item is disabled.                                             |
| `data-state`                                            | `enum`- 'open' \| 'closed' | The open state of the menu or submenu the element controls or belongs to.           |
| `data-menu-sub-trigger`                                 | `''`                                                                                                                                                                                 | Present on the submenu trigger element. |

### Menubar.SubContent

The submenu content displayed when the parent submenu is open.

| Property                                                              | Type                                                                                                                                                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `side` | `enum`- 'top' \| 'bottom' \| 'left' \| 'right'                                     | The preferred side of the anchor to render the floating element against when open. Will be reversed when collisions occur.`Default: bottom`                                                                                                                                                                                                                                                                                        |
| `sideOffset`                        | `number`                                                                                                                                                                                                           | The distance in pixels from the anchor to the floating element.`Default: 0`                                                                                                                                                                                                                                                                                                                                                        |
| `align`                             | `enum`- 'start' \| 'center' \| 'end'                                               | The preferred alignment of the anchor to render the floating element against when open. This may change when collisions occur.`Default: start`                                                                                                                                                                                                                                                                                     |
| `alignOffset`                       | `number`                                                                                                                                                                                                           | The distance in pixels from the anchor to the floating element.`Default: 0`                                                                                                                                                                                                                                                                                                                                                        |
| `arrowPadding`                      | `number`                                                                                                                                                                                                           | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0`                                                                                                                                                                                                                                                                                                  |
| `avoidCollisions`                   | `boolean`                                                                                                                                                                                                          | When `true`, overrides the `side` and `align` options to prevent collisions with the boundary edges.`Default: true`                                                                                                                                                                                                                                                                                                                |
| `collisionBoundary`                 | `union`- Element \| null                                                           | A boundary element or array of elements to check for collisions against.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                   |
| `collisionPadding`                  | `union`- number \| Partial\&lt;Record\&lt;Side, number\&gt;\&gt;                   | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0`                                                                                                                                                                                                                                                                                                  |
| `sticky`                            | `enum`- 'partial' \| 'always'                                                      | The sticky behavior on the align axis. `'partial'` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst `'always'` will keep the content in the boundary regardless.`Default: partial`                                                                                                                                                                                        |
| `hideWhenDetached`                  | `boolean`                                                                                                                                                                                                          | When `true`, hides the content when it is detached from the DOM. This is useful for when you want to hide the content when the user scrolls away.`Default: true`                                                                                                                                                                                                                                                                   |
| `updatePositionStrategy`            | `enum`- 'optimized' \| 'always'                                                    | The strategy to use when updating the position of the content. When `'optimized'` the content will only be repositioned when the trigger is in the viewport. When `'always'` the content will be repositioned whenever the position changes.`Default: optimized`                                                                                                                                                                   |
| `strategy`                          | `enum`- 'fixed' \| 'absolute'                                                      | The positioning strategy to use for the floating element. When `'fixed'` the element will be positioned relative to the viewport. When `'absolute'` the element will be positioned relative to the nearest positioned ancestor.`Default: fixed`                                                                                                                                                                                    |
| `preventScroll`                     | `boolean`                                                                                                                                                                                                          | When `true`, prevents the body from scrolling when the content is open. This is useful when you want to use the content as a modal.`Default: true`                                                                                                                                                                                                                                                                                 |
| `customAnchor`                      | `union`- string \| HTMLElement \| Measurable \| null                               | Use an element other than the trigger to anchor the content to. If provided, the content will be anchored to the provided element instead of the trigger.`Default: null`                                                                                                                                                                                                                                                           |
| `onEscapeKeydown`                   | `function`- (event: KeyboardEvent) => void                                         | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default:  undefined`                                                                                                                                                                                                                    |
| `escapeKeydownBehavior`             | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` |
| `onInteractOutside`                 | `function`- (event: PointerEvent) => void                                          | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default:  undefined`                                                                                                                                                                                                        |
| `onFocusOutside`                    | `function`- (event: FocusEvent) => void                                            | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default:  undefined`                                                                                                                                                                                                                                                  |
| `interactOutsideBehavior`           | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close`  |
| `onOpenAutoFocus`                   | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is opened. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `onCloseAutoFocus`                  | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is closed. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `trapFocus`                         | `boolean`                                                                                                                                                                                                          | Whether or not to trap the focus within the content when open.`Default: true`                                                                                                                                                                                                                                                                                                                                                      |
| `forceMount`                        | `boolean`                                                                                                                                                                                                          | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                                                                                                                                                                                                                                                                 |
| `preventOverflowTextSelection`      | `boolean`                                                                                                                                                                                                          | When `true`, prevents the text selection from overflowing the bounds of the element.`Default: true`                                                                                                                                                                                                                                                                                                                                |
| `dir`                               | `enum`- 'ltr' \| 'rtl'                                                             | The reading direction of the app.`Default: 'ltr'`                                                                                                                                                                                                                                                                                                                                                                                  |
| `loop`                              | `boolean`                                                                                                                                                                                                          | Whether or not to loop through the menu items in when navigating with the keyboard.`Default: false`                                                                                                                                                                                                                                                                                                                                |
| `ref` $bindable        | `HTMLDivElement`                                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                                                                                                                                                                         |
| `children`                          | `Snippet`- Snippet                                                                 | The children content to render.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                                                            |
| `child`                             | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };               | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                                                                                                                                                                  | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                                |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | The open state of the menu or submenu the element controls or belongs to.           |
| `data-menu-sub-content`                           | `''`                                                                                                                                                                                 | Present on the submenu content element. |

### Menubar.SubContentStatic

The submenu content displayed when the parent submenu menu is open. (Static/No Floating UI)

| Property                                                                         | Type                                                                                                                                                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onEscapeKeydown` | `function`- (event: KeyboardEvent) => void                                         | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default:  undefined`                                                                                                                                                                                                                    |
| `escapeKeydownBehavior`                        | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` |
| `onInteractOutside`                            | `function`- (event: PointerEvent) => void                                          | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default:  undefined`                                                                                                                                                                                                        |
| `onFocusOutside`                               | `function`- (event: FocusEvent) => void                                            | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default:  undefined`                                                                                                                                                                                                                                                  |
| `interactOutsideBehavior`                      | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close`  |
| `onOpenAutoFocus`                              | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is opened. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `onCloseAutoFocus`                             | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is closed. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `trapFocus`                                    | `boolean`                                                                                                                                                                                                          | Whether or not to trap the focus within the content when open.`Default: true`                                                                                                                                                                                                                                                                                                                                                      |
| `forceMount`                                   | `boolean`                                                                                                                                                                                                          | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                                                                                                                                                                                                                                                                 |
| `preventOverflowTextSelection`                 | `boolean`                                                                                                                                                                                                          | When `true`, prevents the text selection from overflowing the bounds of the element.`Default: true`                                                                                                                                                                                                                                                                                                                                |
| `dir`                                          | `enum`- 'ltr' \| 'rtl'                                                             | The reading direction of the app.`Default: 'ltr'`                                                                                                                                                                                                                                                                                                                                                                                  |
| `loop`                                         | `boolean`                                                                                                                                                                                                          | Whether or not to loop through the menu items when reaching the end of the list when using the keyboard.`Default: true`                                                                                                                                                                                                                                                                                                            |
| `ref` $bindable                   | `HTMLDivElement`                                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                                                                                                                                                                         |
| `children`                                     | `Snippet`- Snippet                                                                 | The children content to render.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                                                            |
| `child`                                        | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };               | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                                                                                                                                                                  | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                                |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | The open state of the menu or submenu the element controls or belongs to.           |
| `data-menu-sub-content`                           | `''`                                                                                                                                                                                 | Present on the submenu content element. |

----------------------------------------------------

# Meter Documentation

Display real-time measurements within a defined range.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { Meter, useId } from "bits-ui";
  let value = $state(2000);
  const labelId = useId();
  const max = 4000;
  const min = 0;
  const usedPercentage = $derived((value / max) * 100);
  const percentageRemaining = $derived(100 - usedPercentage); const color = $derived.by(() => {
    if (percentageRemaining < 15) return "bg-red-500 dark:bg-red-400";
    if (percentageRemaining < 35) return "bg-orange-500 dark:bg-orange-400";
    if (percentageRemaining < 50) return "bg-yellow-500 dark:bg-yellow-400";
    return "bg-green-500 dark:bg-green-400";
  });
</script>
<div class="flex w-[60%] flex-col gap-2">
  <div class="flex items-center justify-between text-sm font-medium">
    <span id={labelId}> Tokens used </span>
    <span>{value} / {max}</span>
  </div>
  <Meter.Root
    aria-labelledby={labelId}
    aria-valuetext="{value} out of {max}"
    {value}
    {min}
    {max}
    class="bg-dark-10 shadow-mini-inset relative h-[15px] overflow-hidden rounded-full"
  >
    <div
      class="shadow-mini-inset h-full w-full flex-1 rounded-full transition-all duration-1000 ease-in-out {color}"
      style="transform: translateX(-{100 - (100 * (value ?? 0)) / max}%)" ></div>
  </Meter.Root>
</div>
```

While often visually similar, meters and [Progress](/docs/components/progress) bars serve distinct purposes:

**Meter**:

- Displays a **static measurement** within a known range (0-100)  
- Value can fluctuate up/down based on real-time measurements  
- Examples: CPU usage, battery level, sound volume  
- Use when showing current state relative to capacity **Progress bar**:

- Shows **completion status** of a task  
- Value only increases as task progresses  
- Examples: File upload, installation status, form completion  
- Use when tracking advancement toward completion If a progress bar better fits your requirements, check out the [Progress](/docs/components/progress) component.

## Structure

```svelte
<script lang="ts">
 import { Meter } from "bits-ui";
</script>
<Meter.Root />
```

## Reusable Components

It's recommended to use the `Meter` primitive to create your own custom meter component that can be used throughout your application. In the example below, we're using the `Meter` primitive to create a more comprehensive meter component.

```svelte
<script lang="ts">
 import { Meter, useId } from "bits-ui";
 import type { ComponentProps } from "svelte";
 let {
  max = 100,
  value = 0,
  min = 0,
  label,
  valueLabel,
 }: ComponentProps<typeof Meter.Root> & {
  label: string;
  valueLabel: string;
 } = $props();
 const labelId = useId();
</script>
<div>
 <span id={labelId}> {label} </span>
 <span>{valueLabel}</span>
</div>
<Meter.Root aria-labelledby={labelId} aria-valuetext={valueLabel} {value} {min} {max} />
```

You can then use the `MyMeter` component in your application like so:

+page.svelte

```svelte
<script lang="ts">
 import MyMeter from "$lib/components/MyMeter.svelte";
 let value = $state(3000);
 const max = 4000;
</script>
<MyMeter label="Tokens remaining" valueLabel="{value} / {max}" {value} {max} />
```

Of course, you'd want to apply your own styles and other customizations to the `MyMeter` component to fit your application's design.

## Accessibility

If a visual label is used, the ID of the label element should be pass via the `aria-labelledby` prop to `Meter.Root`. If no visual label is used, the `aria-label` prop should be used to provide a text description of the progress bar.

Assistive technologies often present `aria-valuenow` as a percentage. If conveying the value of the meter only in terms of a percentage would not be user friendly, the `aria-valuetext` property should be set to a string that makes the meter value understandable. For example, a battery meter value might be conveyed as `aria-valuetext="50% (6 hours) remaining"`. \[[source](https://www.w3.org/WAI/ARIA/apg/patterns/meter/)]

## API Reference

### Meter.Root

The meter component.

| Property                                                             | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `max` | `number`                                                                                                                                                                                             | The maximum value of the meter.`Default: 100`                                                                                                                                     |
| `min`                              | `number`                                                                                                                                                                                             | The minimum value of the meter.`Default: 0`                                                                                                                                       |
| `value`                            | `number`                                                                                                                                                                                             | The current value of the meter.`Default: 0`                                                                                                                                       |
| `ref` $bindable       | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                         | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                            | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value         | Description                                                                                     |
| ----------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-value` | `''` | The current value of the meter.                                          |
| `data-min`                                        | `''` | The minimum value of the meter.                                          |
| `data-max`                                        | `''` | The maximum value of the meter.                                          |
| `data-meter-root`                                 | `''` | Present on the root element. |

----------------------------------------------------

# Navigation Menu Documentation

A list of links that allow users to navigate between pages of a website.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { NavigationMenu } from "bits-ui";
  import CaretDown from "phosphor-svelte/lib/CaretDown";
  import { cn } from "$lib/utils/styles.js";
  const components: { title: string; href: string; description: string }[] = [
    {
      title: "Alert Dialog",
      href: "/docs/components/alert-dialog",
      description:
        "A modal dialog that interrupts the user with important content and expects a response."
    },
    {
      title: "Link Preview",
      href: "/docs/components/link-preview",
      description:
        "For sighted users to preview content available behind a link."
    },
    {
      title: "Progress",
      href: "/docs/components/progress",
      description:
        "Displays an indicator showing the completion progress of a task, typically displayed as a progress bar."
    },
    {
      title: "Scroll Area",
      href: "/docs/components/scroll-area",
      description: "Visually or semantically separates content."
    },
    {
      title: "Tabs",
      href: "/docs/components/tabs",
      description:
        "A set of layered sections of contentknown as tab panelsthat are displayed one at a time."
    },
    {
      title: "Tooltip",
      href: "/docs/components/tooltip",
      description:
        "A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it."
    }
  ];
  type ListItemProps = {
    className?: string;
    title: string;
    href: string;
    content: string;
  };
</script>
{#snippet ListItem({ className, title, content, href }: ListItemProps)}
  <li>
    <NavigationMenu.Link
      class={cn(
        "hover:bg-muted hover:text-accent-foreground focus:bg-muted focus:text-accent-foreground outline-hidden block select-none space-y-1 rounded-md p-3 leading-none no-underline transition-colors",
        className
      )}
      {href}
    >
      <div class="text-sm font-medium leading-none">{title}</div>
      <p class="text-muted-foreground line-clamp-2 text-sm leading-snug">
        {content}
      </p>
    </NavigationMenu.Link>
  </li>
{/snippet}
<NavigationMenu.Root class="relative z-10 flex w-full justify-center">
  <NavigationMenu.List
    class="group flex list-none items-center justify-center p-1"
  >
    <NavigationMenu.Item value="getting-started">
      <NavigationMenu.Trigger
        class="hover:text-accent-foreground focus:bg-muted focus:text-accent-foreground data-[state=open]:shadow-mini dark:hover:bg-muted dark:data-[state=open]:bg-muted focus:outline-hidden group inline-flex h-8 w-max items-center justify-center rounded-[7px] bg-transparent px-4 py-2 text-sm font-medium transition-colors hover:bg-white disabled:pointer-events-none disabled:opacity-50 data-[state=open]:bg-white"
      >
        Getting started
        <CaretDown
          class="relative top-[1px] ml-1 size-3 transition-transform duration-200 group-data-[state=open]:rotate-180"
          aria-hidden="true"
        />
      </NavigationMenu.Trigger>
      <NavigationMenu.Content
        class="data-[motion=from-end]:animate-enter-from-right data-[motion=from-start]:animate-enter-from-left data-[motion=to-end]:animate-exit-to-right data-[motion=to-start]:animate-exit-to-left absolute left-0 top-0 w-full sm:w-auto"
      >
        <ul
          class="m-0 grid list-none gap-x-2.5 p-3 sm:w-[600px] sm:grid-flow-col sm:grid-rows-3 sm:p-[22px]"
        >
          <li class="row-span-3 mb-2 sm:mb-0">
            <NavigationMenu.Link
              href="/"
              class="from-muted/50 to-muted bg-linear-to-b outline-hidden flex h-full w-full select-none flex-col justify-end rounded-md p-6 no-underline focus:shadow-md"
            >
              <div class="mb-2 mt-4 text-lg font-medium">Bits UI</div>
              <p class="text-muted-foreground text-sm leading-tight">
                The headless components for Svelte.
              </p>
            </NavigationMenu.Link>
          </li>
          {@render ListItem({
            href: "/docs",
            title: "Introduction",
            content: "Headless components for Svelte and SvelteKit"
          })}
          {@render ListItem({
            href: "/docs/getting-started",
            title: "Getting Started",
            content: "How to install and use Bits UI"
          })}
          {@render ListItem({
            href: "/docs/styling",
            title: "Styling",
            content: "How to style Bits UI components"
          })}
        </ul>
      </NavigationMenu.Content>
    </NavigationMenu.Item>
    <NavigationMenu.Item>
      <NavigationMenu.Trigger
        class="hover:text-accent-foreground focus:bg-muted focus:text-accent-foreground data-[state=open]:shadow-mini dark:hover:bg-muted dark:data-[state=open]:bg-muted focus:outline-hidden group inline-flex h-8 w-max items-center justify-center rounded-[7px] bg-transparent px-4 py-2 text-sm font-medium transition-colors hover:bg-white disabled:pointer-events-none disabled:opacity-50 data-[state=open]:bg-white"
      >
        Components
        <CaretDown
          class="relative top-[1px] ml-1 size-3 transition-transform duration-200 group-data-[state=open]:rotate-180"
          aria-hidden="true"
        />
      </NavigationMenu.Trigger>
      <NavigationMenu.Content
        class="data-[motion=from-end]:animate-enter-from-right data-[motion=from-start]:animate-enter-from-left data-[motion=to-end]:animate-exit-to-right data-[motion=to-start]:animate-exit-to-left absolute left-0 top-0 w-full sm:w-auto"
      >
        <ul
          class="grid gap-3 p-3 sm:w-[400px] sm:p-6 md:w-[500px] md:grid-cols-2 lg:w-[600px]"
        >
          {#each components as component (component.title)}
            {@render ListItem({
              href: component.href,
              title: component.title,
              content: component.description
            })}
          {/each}
        </ul>
      </NavigationMenu.Content>
    </NavigationMenu.Item>
    <NavigationMenu.Item>
      <NavigationMenu.Link
        class="hover:text-accent-foreground focus:bg-muted focus:text-accent-foreground data-[state=open]:shadow-mini dark:hover:bg-muted dark:data-[state=open]:bg-muted focus:outline-hidden group inline-flex h-8 w-max items-center justify-center rounded-[7px] bg-transparent px-4 py-2 text-sm font-medium transition-colors hover:bg-white disabled:pointer-events-none disabled:opacity-50 data-[state=open]:bg-white"
        href="/docs"
      >
        <span class="hidden sm:inline"> Documentation </span>
        <span class="inline sm:hidden"> Docs </span>
      </NavigationMenu.Link>
    </NavigationMenu.Item>
    <NavigationMenu.Indicator
      class="data-[state=hidden]:animate-fade-out data-[state=visible]:animate-fade-in top-full z-10 flex h-2.5 items-end justify-center overflow-hidden opacity-100 transition-[all,transform_250ms_ease] duration-200 data-[state=hidden]:opacity-0"
    >
      <div
        class="bg-border relative top-[70%] size-2.5 rotate-[45deg] rounded-tl-[2px]"
      ></div>
    </NavigationMenu.Indicator>
  </NavigationMenu.List>
  <div
    class="perspective-[2000px] absolute left-0 top-full flex w-full justify-center"
  >
    <NavigationMenu.Viewport
      class="text-popover-foreground bg-background data-[state=closed]:animate-scale-out data-[state=open]:animate-scale-in relative mt-2.5 h-[var(--bits-navigation-menu-viewport-height)] w-full origin-[top_center] overflow-hidden rounded-md border shadow-lg transition-[width,_height] duration-200 sm:w-[var(--bits-navigation-menu-viewport-width)] "
    />
  </div>
</NavigationMenu.Root>
```

## Structure

```svelte
<script lang="ts">
 import { NavigationMenu } from "bits-ui";
</script>
<NavigationMenu.Root>
 <NavigationMenu.List>
  <NavigationMenu.Item>
   <NavigationMenu.Trigger />
   <NavigationMenu.Content />
  </NavigationMenu.Item>
  <NavigationMenu.Item>
   <NavigationMenu.Trigger />
   <NavigationMenu.Content>
    <NavigationMenu.Link />
   </NavigationMenu.Content>
  </NavigationMenu.Item>
  <NavigationMenu.Item>
   <NavigationMenu.Link />
  </NavigationMenu.Item>
  <NavigationMenu.Item>
   <NavigationMenu.Trigger />
   <NavigationMenu.Content>
    <NavigationMenu.Sub>
     <NavigationMenu.List />
     <NavigationMenu.Viewport />
    </NavigationMenu.Sub>
   </NavigationMenu.Content>
  </NavigationMenu.Item>
  <NavigationMenu.Indicator />
 </NavigationMenu.List>
 <NavigationMenu.Viewport />
</NavigationMenu.Root>
```

## Usage

### Vertical

You can create a vertical menu by using the `orientation` prop.

```svelte
<NavigationMenu.Root orientation="vertical">
</NavigationMenu.Root>
```

### Flexible Layouts

Use the `Viewport` component when you need extra control over where `Content` is rendered. This can be useful when your design requires an adjusted DOM structure or if you need flexibility to achieve advanced animations. Tab focus will be managed automatically.

```svelte
<NavigationMenu.Root>
 <NavigationMenu.List>
  <NavigationMenu.Item>
   <NavigationMenu.Trigger>Item one</NavigationMenu.Trigger>
   <NavigationMenu.Content>Item one content</NavigationMenu.Content>
  </NavigationMenu.Item>
  <NavigationMenu.Item>
   <NavigationMenu.Trigger>Item two</NavigationMenu.Trigger>
   <NavigationMenu.Content>Item two content</NavigationMenu.Content>
  </NavigationMenu.Item>
 </NavigationMenu.List>
 <NavigationMenu.Viewport />
</NavigationMenu.Root>
```

### With Indicator

You can use the optional `Indicator` component to highlight the currently active `Trigger`, which is useful when you want to provide an animated visual cue such as an arrow or highlight to accompany the `Viewport`.

```svelte
<NavigationMenu.Root>
 <NavigationMenu.List>
  <NavigationMenu.Item>
   <NavigationMenu.Trigger>Item one</NavigationMenu.Trigger>
   <NavigationMenu.Content>Item one content</NavigationMenu.Content>
  </NavigationMenu.Item>
  <NavigationMenu.Item>
   <NavigationMenu.Trigger>Item two</NavigationMenu.Trigger>
   <NavigationMenu.Content>Item two content</NavigationMenu.Content>
  </NavigationMenu.Item>
  <NavigationMenu.Indicator />
 </NavigationMenu.List>
 <NavigationMenu.Viewport />
</NavigationMenu.Root>
```

### Submenus

You can create a submenu by nesting your navigation menu and using the `Navigation.Sub` component in place of `NavigationMenu.Root`. Submenus work differently than the `Root` menus and are more similar to [Tabs](/docs/components/tabs) in that one item should always be active, so be sure to assign and pass a `value` prop.

```svelte
<NavigationMenu.Root>
 <NavigationMenu.List>
  <NavigationMenu.Item>
   <NavigationMenu.Trigger>Item one</NavigationMenu.Trigger>
   <NavigationMenu.Content>Item one content</NavigationMenu.Content>
  </NavigationMenu.Item>
  <NavigationMenu.Item>
   <NavigationMenu.Trigger>Item two</NavigationMenu.Trigger>
   <NavigationMenu.Content>
    <NavigationMenu.Sub value="sub1">
     <NavigationMenu.List>
      <NavigationMenu.Item value="sub1">
       <NavigationMenu.Trigger>Sub item one</NavigationMenu.Trigger>
       <NavigationMenu.Content>Sub item one content</NavigationMenu.Content>
      </NavigationMenu.Item>
      <NavigationMenu.Item value="sub2">
       <NavigationMenu.Trigger>Sub item two</NavigationMenu.Trigger>
       <NavigationMenu.Content>Sub item two content</NavigationMenu.Content>
      </NavigationMenu.Item>
     </NavigationMenu.List>
    </NavigationMenu.Sub>
   </NavigationMenu.Content>
  </NavigationMenu.Item>
 </NavigationMenu.List>
</NavigationMenu.Root>
```

### Advanced Animation

We expose `--bits-navigation-menu-viewport-[width|height]` and `data-motion['from-start'|'to-start'|'from-end'|'to-end']` to allow you to animate the `NavigationMenu.Viewport` size and `NavigationMenu.Content` position based on the enter/exit direction.

Combining these with `position: absolute;` allows you to create smooth overlapping animation effects when moving between items.

```svelte
<NavigationMenu.Root>
 <NavigationMenu.List>
  <NavigationMenu.Item>
   <NavigationMenu.Trigger>Item one</NavigationMenu.Trigger>
   <NavigationMenu.Content class="NavigationMenuContent">
    Item one content
   </NavigationMenu.Content>
  </NavigationMenu.Item>
  <NavigationMenu.Item>
   <NavigationMenu.Trigger>Item two</NavigationMenu.Trigger>
   <NavigationMenu.Content class="NavigationMenuContent">
    Item two content
   </NavigationMenu.Content>
  </NavigationMenu.Item>
 </NavigationMenu.List>
 <NavigationMenu.Viewport class="NavigationMenuViewport" />
</NavigationMenu.Root>
```

```css
/* app.css */
.NavigationMenuContent {
 position: absolute;
 top: 0;
 left: 0;
 animation-duration: 250ms;
 animation-timing-function: ease;
}
.NavigationMenuContent[data-motion="from-start"] {
 animation-name: enter-from-left;
}
.NavigationMenuContent[data-motion="from-end"] {
 animation-name: enter-from-right;
}
.NavigationMenuContent[data-motion="to-start"] {
 animation-name: exit-to-left;
}
.NavigationMenuContent[data-motion="to-end"] {
 animation-name: exit-to-right;
}
.NavigationMenuViewport {
 position: relative;
 width: var(--bits-navigation-menu-viewport-width);
 height: var(--bits-navigation-menu-viewport-height);
 transition:
  width,
  height,
  250ms ease;
}
@keyframes enter-from-right {
 from {
  opacity: 0;
  transform: translateX(200px);
 }
 to {
  opacity: 1;
  transform: translateX(0);
 }
}
@keyframes enter-from-left {
 from {
  opacity: 0;
  transform: translateX(-200px);
 }
 to {
  opacity: 1;
  transform: translateX(0);
 }
}
@keyframes exit-to-right {
 from {
  opacity: 1;
  transform: translateX(0);
 }
 to {
  opacity: 0;
  transform: translateX(200px);
 }
}
@keyframes exit-to-left {
 from {
  opacity: 1;
  transform: translateX(0);
 }
 to {
  opacity: 0;
  transform: translateX(-200px);
 }
}
```

### Force Mounting

You may wish for the links in the Navigation Menu to persist in the DOM, regardless of whether the menu is open or not. This is particularly useful for SEO purposes. You can achieve this by using the `forceMount` prop on the `NavigationMenu.Content` and `NavigationMenu.Viewport` components.

##### Warning

**Note:** Using `forceMount` requires you to manage the visibility of the elements yourself, using the `data-state` attributes on the `NavigationMenu.Content` and `NavigationMenu.Viewport` components.

```svelte
<NavigationMenu.Content forceMount></NavigationMenu.Content>
<NavigationMenu.Viewport forceMount></NavigationMenu.Viewport>
```

```svelte
<script lang="ts">
  import { NavigationMenu } from "bits-ui";
  import CaretDown from "phosphor-svelte/lib/CaretDown";
  import { cn } from "$lib/utils/styles.js";
  const components: { title: string; href: string; description: string }[] = [
    {
      title: "Alert Dialog",
      href: "/docs/components/alert-dialog",
      description:
        "A modal dialog that interrupts the user with important content and expects a response."
    },
    {
      title: "Link Preview",
      href: "/docs/components/link-preview",
      description:
        "For sighted users to preview content available behind a link."
    },
    {
      title: "Progress",
      href: "/docs/components/progress",
      description:
        "Displays an indicator showing the completion progress of a task, typically displayed as a progress bar."
    },
    {
      title: "Scroll Area",
      href: "/docs/components/scroll-area",
      description: "Visually or semantically separates content."
    },
    {
      title: "Tabs",
      href: "/docs/components/tabs",
      description:
        "A set of layered sections of contentknown as tab panelsthat are displayed one at a time."
    },
    {
      title: "Tooltip",
      href: "/docs/components/tooltip",
      description:
        "A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it."
    }
  ];
  type ListItemProps = {
    className?: string;
    title: string;
    href: string;
    content: string;
  };
</script>
{#snippet ListItem({ className, title, content, href }: ListItemProps)}
  <li>
    <NavigationMenu.Link
      class={cn(
        "hover:bg-muted hover:text-accent-foreground focus:bg-muted focus:text-accent-foreground outline-hidden block select-none space-y-1 rounded-md p-3 leading-none no-underline transition-colors",
        className
      )}
      {href}
    >
      <div class="text-sm font-medium leading-none">{title}</div>
      <p class="text-muted-foreground line-clamp-2 text-sm leading-snug">
        {content}
      </p>
    </NavigationMenu.Link>
  </li>
{/snippet}
<NavigationMenu.Root class="relative z-10 flex w-full justify-center">
  <NavigationMenu.List
    class="group flex list-none items-center justify-center p-1"
  >
    <NavigationMenu.Item value="getting-started">
      <NavigationMenu.Trigger
        class="hover:text-accent-foreground focus:bg-muted focus:text-accent-foreground data-[state=open]:shadow-mini dark:hover:bg-muted dark:data-[state=open]:bg-muted focus:outline-hidden group inline-flex h-8 w-max items-center justify-center rounded-[7px] bg-transparent px-4 py-2 text-sm font-medium transition-colors hover:bg-white disabled:pointer-events-none disabled:opacity-50 data-[state=open]:bg-white"
      >
        Getting started
        <CaretDown
          class="relative top-[1px] ml-1 size-3 transition-transform duration-200 group-data-[state=open]:rotate-180"
          aria-hidden="true"
        />
      </NavigationMenu.Trigger>
      <NavigationMenu.Content
        class="data-[motion=from-end]:animate-enter-from-right data-[motion=from-start]:animate-enter-from-left data-[motion=to-end]:animate-exit-to-right data-[motion=to-start]:animate-exit-to-left absolute left-0 top-0 w-full data-[state=closed]:hidden sm:w-auto"
        forceMount
      >
        <ul
          class="m-0 grid list-none gap-x-2.5 p-3 sm:w-[600px] sm:grid-flow-col sm:grid-rows-3 sm:p-[22px]"
        >
          <li class="row-span-3 mb-2 sm:mb-0">
            <NavigationMenu.Link
              href="/"
              class="from-muted/50 to-muted bg-linear-to-b outline-hidden flex h-full w-full select-none flex-col justify-end rounded-md p-6 no-underline focus:shadow-md"
            >
              <div class="mb-2 mt-4 text-lg font-medium">Bits UI</div>
              <p class="text-muted-foreground text-sm leading-tight">
                The headless components for Svelte.
              </p>
            </NavigationMenu.Link>
          </li>
          {@render ListItem({
            href: "/docs",
            title: "Introduction",
            content: "Headless components for Svelte and SvelteKit"
          })}
          {@render ListItem({
            href: "/docs/getting-started",
            title: "Getting Started",
            content: "How to install and use Bits UI"
          })}
          {@render ListItem({
            href: "/docs/styling",
            title: "Styling",
            content: "How to style Bits UI components"
          })}
        </ul>
      </NavigationMenu.Content>
    </NavigationMenu.Item>
    <NavigationMenu.Item>
      <NavigationMenu.Trigger
        class="hover:text-accent-foreground focus:bg-muted focus:text-accent-foreground data-[state=open]:shadow-mini dark:hover:bg-muted dark:data-[state=open]:bg-muted focus:outline-hidden group inline-flex h-8 w-max items-center justify-center rounded-[7px] bg-transparent px-4 py-2 text-sm font-medium transition-colors hover:bg-white disabled:pointer-events-none disabled:opacity-50 data-[state=open]:bg-white"
      >
        Components
        <CaretDown
          class="relative top-[1px] ml-1 size-3 transition-transform duration-200 group-data-[state=open]:rotate-180"
          aria-hidden="true"
        />
      </NavigationMenu.Trigger>
      <NavigationMenu.Content
        forceMount
        class="data-[motion=from-end]:animate-enter-from-right data-[motion=from-start]:animate-enter-from-left data-[motion=to-end]:animate-exit-to-right data-[motion=to-start]:animate-exit-to-left absolute left-0 top-0 w-full data-[state=closed]:hidden sm:w-auto"
      >
        <ul
          class="grid gap-3 p-3 sm:w-[400px] sm:p-6 md:w-[500px] md:grid-cols-2 lg:w-[600px]"
        >
          {#each components as component (component.title)}
            {@render ListItem({
              href: component.href,
              title: component.title,
              content: component.description
            })}
          {/each}
        </ul>
      </NavigationMenu.Content>
    </NavigationMenu.Item>
    <NavigationMenu.Item>
      <NavigationMenu.Link
        class="hover:text-accent-foreground focus:bg-muted focus:text-accent-foreground data-[state=open]:shadow-mini dark:hover:bg-muted dark:data-[state=open]:bg-muted focus:outline-hidden group inline-flex h-8 w-max items-center justify-center rounded-[7px] bg-transparent px-4 py-2 text-sm font-medium transition-colors hover:bg-white disabled:pointer-events-none disabled:opacity-50 data-[state=open]:bg-white"
        href="/docs"
      >
        <span class="hidden sm:inline"> Documentation </span>
        <span class="inline sm:hidden"> Docs </span>
      </NavigationMenu.Link>
    </NavigationMenu.Item>
    <NavigationMenu.Indicator
      class="data-[state=hidden]:animate-fade-out data-[state=visible]:animate-fade-in top-full z-10 flex h-2.5 items-end justify-center overflow-hidden opacity-100 transition-[all,transform_250ms_ease] duration-200 data-[state=hidden]:opacity-0"
    >
      <div
        class="bg-border relative top-[70%] size-2.5 rotate-[45deg] rounded-tl-[2px]"
      ></div>
    </NavigationMenu.Indicator>
  </NavigationMenu.List>
  <div
    class="perspective-[2000px] absolute left-0 top-full flex w-full justify-center"
  >
    <NavigationMenu.Viewport
      forceMount
      class="text-popover-foreground bg-background data-[state=closed]:animate-scale-out data-[state=open]:animate-scale-in relative mt-2.5 h-[var(--bits-navigation-menu-viewport-height)] w-full origin-[top_center] overflow-hidden rounded-md border shadow-lg transition-[width,_height] duration-200 data-[state=closed]:hidden sm:w-[var(--bits-navigation-menu-viewport-width)]"
    />
  </div>
</NavigationMenu.Root>
```

## API Reference

### NavigationMenu.Root

The root navigation menu component which manages & scopes the state of the navigation menu.

| Property                                                                                      | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` $bindable | `string`                                                                                                                                                                                             | The value of the currently active menu.`Default:  undefined`                                                                                                                   |
| `onValueChange`                                             | `function`- (value: string) => void                                  | A callback function called when the active menu value changes.`Default:  undefined`                                                                                            |
| `dir`                                                       | `enum`- 'ltr' \| 'rtl'                                               | The reading direction of the app.`Default: 'ltr'`                                                                                                                                 |
| `skipDelayDuration`                                         | `number`                                                                                                                                                                                             | How much time a user has to enter another trigger without incurring a delay again.`Default: 300`                                                                                  |
| `delayDuration`                                             | `number`                                                                                                                                                                                             | The duration from when the mouse enters a trigger until the content opens.`Default: 200`                                                                                          |
| `orientation`                                               | `enum`- 'horizontal' \| 'vertical'                                   | The orientation of the menu.`Default: horizontal`                                                                                                                                 |
| `ref` $bindable                                | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                  | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                     | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | ### NavigationMenu.List

A menu within the menubar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLUListElement`                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | ### NavigationMenu.Item

A list item within the navigation menu.

| Property                                                               | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` | `string`                                                                                                                                                                                             | The value of the item.`Default:  undefined`                                                                                                                                    |
| `ref` $bindable         | `HTMLLiElement`                                                                                                                                                                                      | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                           | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                              | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | ### NavigationMenu.Trigger

The button element which toggles the dropdown menu.

| Property                                                                  | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `disabled` | `boolean`                                                                                                                                                                                            | Whether or not the trigger is disabled.`Default: false`                                                                                                                           |
| `ref` $bindable            | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                              | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                 | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | ### NavigationMenu.Content

The content displayed when the dropdown menu is open.

| Property                                                                           | Type                                                                                                                                                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onInteractOutside` | `function`- (event: PointerEvent) => void                                          | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default:  undefined`                                                                                                                                                                                                        |
| `onFocusOutside`                                 | `function`- (event: FocusEvent) => void                                            | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default:  undefined`                                                                                                                                                                                                                                                  |
| `interactOutsideBehavior`                        | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close`  |
| `onEscapeKeydown`                                | `function`- (event: KeyboardEvent) => void                                         | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default:  undefined`                                                                                                                                                                                                                    |
| `escapeKeydownBehavior`                          | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` |
| `forceMount`                                     | `boolean`                                                                                                                                                                                                          | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                                                                                                                                                                                                                                                                 |
| `ref` $bindable                     | `HTMLDivElement`                                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                                                                                                                                                                         |
| `children`                                       | `Snippet`                                                                                                                                                                                                          | The children content to render.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                                                            |
| `child`                                          | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };               | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                                                                                                                                                                  | ### NavigationMenu.Link

A link within the navigation menu.

| Property                                                                | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `active` | `boolean`                                                                                                                                                                                            | Whether or not the link is active.`Default: false`                                                                                                                                |
| `onSelect`                            | `function`- () => void                                                | A callback function called when the link is selected.`Default:  undefined`                                                                                                     |
| `ref` $bindable          | `HTMLAnchorElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                            | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                               | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | ### NavigationMenu.Viewport

The viewport element for the navigation menu, which is used to contain the menu items.

| Property                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `forceMount` | `boolean`                                                                                                                                                                                            | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                |
| `ref` $bindable              | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | ### NavigationMenu.Indicator

The indicator element for the navigation menu, which is used to indicate the current active item.

| Property                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `forceMount` | `boolean`                                                                                                                                                                                            | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                |
| `ref` $bindable              | `HTMLSpanElement`                                                                                                                                                                                    | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` |

----------------------------------------------------

# Pagination Documentation

Facilitates navigation between pages.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { Pagination } from "bits-ui";
  import CaretLeft from "phosphor-svelte/lib/CaretLeft";
  import CaretRight from "phosphor-svelte/lib/CaretRight";
</script>
<Pagination.Root count={100} perPage={10}>
  {#snippet children({ pages, range })}
    <div class="my-8 flex items-center">
      <Pagination.PrevButton
        class="hover:bg-dark-10 disabled:text-muted-foreground mr-[25px] inline-flex size-10 items-center justify-center rounded-[9px] bg-transparent active:scale-[0.98] disabled:cursor-not-allowed hover:disabled:bg-transparent"
      >
        <CaretLeft class="size-6" />
      </Pagination.PrevButton>
      <div class="flex items-center gap-2.5">
        {#each pages as page (page.key)}
          {#if page.type === "ellipsis"}
            <div
              class="text-foreground-alt select-none text-[15px] font-medium"
            >
              ...
            </div>
          {:else}
            <Pagination.Page
              {page}
              class="hover:bg-dark-10 data-selected:bg-foreground data-selected:text-background inline-flex size-10 select-none items-center justify-center rounded-[9px] bg-transparent text-[15px] font-medium active:scale-[0.98] disabled:cursor-not-allowed disabled:opacity-50 hover:disabled:bg-transparent"
            >
              {page.value}
            </Pagination.Page>
          {/if}
        {/each}
      </div>
      <Pagination.NextButton
        class="hover:bg-dark-10 disabled:text-muted-foreground ml-[29px] inline-flex size-10 items-center justify-center rounded-[9px] bg-transparent active:scale-[0.98] disabled:cursor-not-allowed hover:disabled:bg-transparent"
      >
        <CaretRight class="size-6" />
      </Pagination.NextButton>
    </div>
    <p class="text-muted-foreground text-center text-[13px]">
      Showing {range.start} - {range.end} </p>
  {/snippet}
</Pagination.Root>
```

## Structure

```svelte
<script lang="ts">
 import { Pagination } from "bits-ui";
</script>
<Pagination.Root let:pages>
 <Pagination.PrevButton />
 {#each pages as page (page.key)}
  <Pagination.Page {page} />
 {/each}
 <Pagination.NextButton />
</Pagination.Root>
```

## Managing Page State

This section covers how to manage the `page` state of the component.

### Two-Way Binding

Use `bind:page` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { Pagination } from "bits-ui";
 let myPage = $state(1);
</script>
<button onclick={() => (myPage = 2)}> Go to page 2 </button>
<Pagination.Root bind:pressed={myPage}>
</Pagination.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { Pagination } from "bits-ui";
 let myPage = $state(1);
 function getPage() {
  return myPage;
 }
 function setPage(newPage: number) {
  myPage = newPage;
 }
</script>
<Pagination.Root bind:page={getPage, setPage}>
</Pagination.Root>
```

## Ellipsis

The `pages` snippet prop consists of two types of items: `'page'` and `'ellipsis'`. The `'page'` type represents an actual page number, while the `'ellipsis'` type represents a placeholder for rendering an ellipsis between pages.

## API Reference

### Pagination.Root

The root pagination component which contains all other pagination components.

| Property                                                                                     | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `count` required | `number`                                                                                                                                                                                             | The total number of items.`Default:  undefined`                                                                                                                                |
| `page` $bindable                              | `number`                                                                                                                                                                                             | The selected page. You can bind this to a variable to control the selected page from outside the component.`Default:  undefined`                                               |
| `onPageChange`                                             | `function`- (page: number) => void                                   | A function called when the selected page changes.`Default:  undefined`                                                                                                         |
| `perPage`                                                  | `number`                                                                                                                                                                                             | The number of items per page.`Default: 1`                                                                                                                                         |
| `siblingCount`                                             | `number`                                                                                                                                                                                             | The number of page triggers to show on either side of the current page.`Default: 1`                                                                                               |
| `loop`                                                     | `boolean`                                                                                                                                                                                            | Whether or not the pagination should loop through the items when reaching the end while navigating with the keyboard.`Default: false`                                             |
| `orientation`                                              | `enum`- 'horizontal' \| 'vertical'                                   | The orientation of the pagination. This determines how keyboard navigation will work with the component.`Default: horizontal`                                                     |
| `ref` $bindable                               | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                 | `Snippet`- Snippet                                                   | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                    | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | ### Pagination.Page

A button that triggers a page change.

| Property                                                              | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Description                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `page` | `PageItem`- export type Page = { type: "page"; /\*\* The page number the 'PageItem' represents \*/ value: number; } export type Ellipsis = { type: "ellipsis"; } export type PageItem = (Page \| Ellipsis) & { /\*\* Unique key for the item, for svelte #each block \*/ key: string; } | The page item this component represents.`Default:  undefined`                                                                                                                  |
| `ref` $bindable        | `HTMLButtonElement`                                                                                                                                                                                                                                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                          | `Snippet`                                                                                                                                                                                                                                                                                                                                                                                                               | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                             | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };                                                                                                                                                                                                                    | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                             |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-selected` | `''` | Present on the current page element.                                             |
| `data-pagination-page`                               | `''` | Present on the page trigger element. |

### Pagination.PrevButton

The previous button of the pagination.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                              | Value         | Description                                                                                                |
| ---------------------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-pagination-prev-button` | `''` | Present on the previous button element. |

### Pagination.NextButton

The next button of the pagination.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                              | Value         | Description                                                                                            |
| ---------------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-pagination-next-button` | `''` | Present on the next button element. |

----------------------------------------------------

# PIN Input Documentation

Allows users to input a sequence of one-character alphanumeric inputs.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import {
    PinInput,
    REGEXP_ONLY_DIGITS,
    type PinInputRootSnippetProps
  } from "bits-ui";
  import { toast } from "svelte-sonner";
  import { cn } from "$lib/utils/styles.js";
  let value = $state("");
  type CellProps = PinInputRootSnippetProps["cells"][0];
  function onComplete() {
    toast.success(`Completed with value ${value}`);
    value = "";
  }
</script>
<PinInput.Root
  bind:value
  class="group/pininput text-foreground has-disabled:opacity-30 flex items-center"
  maxlength={6}
  {onComplete}
  pattern={REGEXP_ONLY_DIGITS}
>
  {#snippet children({ cells })}
    <div class="flex">
      {#each cells.slice(0, 3) as cell}
        {@render Cell(cell)}
      {/each}
    </div>
    <div class="flex w-10 items-center justify-center">
      <div class="bg-border h-1 w-3 rounded-full"></div>
    </div>
    <div class="flex">
      {#each cells.slice(3, 6) as cell}
        {@render Cell(cell)}
      {/each}
    </div>
  {/snippet}
</PinInput.Root>
{#snippet Cell(cell: CellProps)}
  <PinInput.Cell
    {cell}
    class={cn(
      // Custom class to override global focus styles
      "focus-override",
      "relative h-14 w-10 text-[2rem]",
      "flex items-center justify-center",
      "transition-all duration-75",
      "border-foreground/20 border-y border-r first:rounded-l-md first:border-l last:rounded-r-md",
      "text-foreground group-focus-within/pininput:border-foreground/40 group-hover/pininput:border-foreground/40",
      "outline-0",
      "data-active:outline-1 data-active:outline-white"
    )}
  >
    {#if cell.char !== null}
      <div>
        {cell.char}
      </div>
    {/if}
    {#if cell.hasFakeCaret}
      <div
        class="animate-caret-blink pointer-events-none absolute inset-0 flex items-center justify-center"
      >
        <div class="h-8 w-px bg-white"></div>
      </div>
    {/if}
  </PinInput.Cell>
{/snippet}
```

## Overview

The PIN Input component provides a customizable solution for One-Time Password (OTP), Two-Factor Authentication (2FA), or Multi-Factor Authentication (MFA) input fields. Due to the lack of a native HTML element for these purposes, developers often resort to either basic input fields or custom implementations. This component offers a robust, accessible, and flexible alternative.

##### Credits

This component is derived from and would not have been possible without the work done by [Guilherme Rodz](https://x.com/guilhermerodz) with [Input OTP](https://github.com/guilhermerodz/input-otp).

## Key Features

- **Invisible Input Technique**: Utilizes an invisible input element for seamless integration with form submissions and browser autofill functionality.  
- **Customizable Appearance**: Allows for custom designs while maintaining core functionality.  
- **Accessibility**: Ensures keyboard navigation and screen reader compatibility.  
- **Flexible Configuration**: Supports various PIN lengths and input types (numeric, alphanumeric). ## Architecture

1. 
   **Root Container**: A relatively positioned root element that encapsulates the entire component.
2. 
   **Invisible Input**: A hidden input field that manages the actual value and interacts with the browser's built-in features.
3. 
   **Visual Cells**: Customizable elements representing each character of the PIN, rendered as siblings to the invisible input.

This structure allows for a seamless user experience while providing developers with full control over the visual representation.

## Structure

```svelte
<script lang="ts">
 import { PinInput } from "bits-ui";
</script>
<PinInput.Root maxlength={6}>
 {#snippet children({ cells })}
  {#each cells as cell}
   <PinInput.Cell {cell} />
  {/each}
 {/snippet}
</PinInput.Root>
```

## Managing Value State

This section covers how to manage the `value` state of the component.

### Two-Way Binding

Use `bind:value` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { PinInput } from "bits-ui";
 let myValue = $state("");
</script>
<button onclick={() => (myValue = "123456")}> Set value to 123456 </button>
<PinInput.Root bind:value={myValue}>
</PinInput.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { PinInput } from "bits-ui";
 let myValue = $state("");
 function getValue() {
  return myValue;
 }
 function setValue(newValue: string) {
  myValue = newValue;
 }
</script>
<PinInput.Root bind:value={getValue, setValue}>
</PinInput.Root>
```

## Paste Transformation

The `pasteTransformer` prop allows you to sanitize/transform pasted text. This can be useful for cleaning up pasted text, like removing hyphens or other characters that should not make it into the input. This function should return the sanitized text, which will be used as the new value of the input.

```svelte
<script lang="ts">
 import { PinInput } from "bits-ui";
</script>
<PinInput.Root pasteTransformer={(text) => text.replace(/-/g, "")}>
</PinInput.Root>
```

## HTML Forms

The `PinInput.Root` component is designed to work seamlessly with HTML forms. Simply pass the `name` prop to the `PinInput.Root` component and the input will be submitted with the form.

### Submit On Complete

To submit the form when the input is complete, you can use the `onComplete` prop.

```svelte
<script lang="ts">
 import { PinInput } from "bits-ui";
 let form = $state<HTMLFormElement>(null!);
</script>
<form method="POST" bind:this={form}>
 <PinInput.Root name="mfaCode" onComplete={() => form.submit()}>
 </PinInput.Root>
</form>
```

## Patterns

You can use the `pattern` prop to restrict the characters that can be entered or pasted into the input.

##### Note!

Client-side validation cannot replace server-side validation. Use this in addition to server-side validation for an improved user experience.

Bits UI exports a few common patterns that you can import and use in your application.

- `REGEXP_ONLY_DIGITS` \- Only allow digits to be entered.
- `REGEXP_ONLY_CHARS` \- Only allow characters to be entered.
- `REGEXP_ONLY_DIGITS_AND_CHARS` \- Only allow digits and characters to be entered.

```svelte
<script lang="ts">
 import { PinInput, REGEXP_ONLY_DIGITS } from "bits-ui";
</script>
<PinInput.Root pattern={REGEXP_ONLY_DIGITS}>
</PinInput.Root>
```

## API Reference

### PINInput.Root

The pin input container component.

| Property                                                                                      | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                                                                                                                                               |
| -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` $bindable | `string`                                                                                                                                                                                             | The value of the input.`Default:  undefined`                                                                                                                                                                                                                                                             |
| `onValueChange`                                             | `function`- (value: string) => void                                  | A callback function that is called when the value of the input changes.`Default:  undefined`                                                                                                                                                                                                             |
| `disabled`                                                  | `boolean`                                                                                                                                                                                            | Whether or not the pin input is disabled.`Default: false`                                                                                                                                                                                                                                                   |
| `textalign`                                                 | `enum`- 'left' \| 'center' \| 'right'                                | Where is the text located within the input. Affects click-holding or long-press behavior`Default: 'left'`                                                                                                                                                                                                   |
| `maxlength`                                                 | `number`                                                                                                                                                                                             | The maximum length of the pin input.`Default: 6`                                                                                                                                                                                                                                                            |
| `onComplete`                                                | `function`- (...args: any\[]) => void                                | A callback function that is called when the input is completely filled.`Default:  undefined`                                                                                                                                                                                                             |
| `pasteTransformer`                                          | `function`- (text: string) => string                                 | A callback function that is called when the user pastes text into the input. It receives the pasted text as an argument and should return the sanitized text. Useful for cleaning up pasted text, like removing hyphens or other characters that should not make it into the input.`Default:  undefined` |
| `inputId`                                                   | `string`                                                                                                                                                                                             | Optionally provide an ID to apply to the hidden input element.`Default:  undefined`                                                                                                                                                                                                                      |
| `pushPasswordManagerStrategy`                               | `enum`- 'increase-width' \| 'none'                                   | Enabled by default, it's an optional strategy for detecting Password Managers in the page and then shifting their badges to the right side, outside the input.`Default:  undefined`                                                                                                                      |
| `ref` $bindable                                | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                                                  |
| `children`                                                  | `Snippet`- Snippet                                                   | The children content to render.`Default:  undefined`                                                                                                                                                                                                                                                     |
| `child`                                                     | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                                           | | Data Attribute                                      | Value         | Description                                                                                     |
| -------------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-pin-input-root` | `''` | Present on the root element. |

### PINInput.Cell

A single cell of the pin input.

| Property                                                              | Type                                                                                                                                                                                                                                                                                                                                                                                                                | Description                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cell` | `object`- type Cell = { /\*\* The character displayed in the cell. \*/ char: string \| null \| undefined; /\*\* Whether the cell is active. \*/ isActive: boolean; /\*\* Whether the cell has a fake caret. \*/ hasFakeCaret: boolean; } | The cell object provided by the `cells` snippet prop from the `PinInput.Root` component.`Default:  undefined`                                                                  |
| `ref` $bindable        | `HTMLDivElement`                                                                                                                                                                                                                                                                                                                                                         | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                          | `Snippet`                                                                                                                                                                                                                                                                                                                                                                | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                             | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };                                                                                                                                                                     | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                              | Value         | Description                                                                                     |
| ------------------------------------------------------------------------------ | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-active` | `''` | Present when the cell is active.                                         |
| `data-inactive`                                    | `''` | Present when the cell is inactive.                                       |
| `data-pin-input-cell`                              | `''` | Present on the cell element. |

----------------------------------------------------

# Popover Documentation

Display supplementary content or information when users interact with specific elements.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { Popover, Separator, Toggle } from "bits-ui";
  import ImageSquare from "phosphor-svelte/lib/ImageSquare";
  import LinkSimpleHorizontalBreak from "phosphor-svelte/lib/LinkSimpleHorizontalBreak";
  let width = $state(1024);
  let height = $state(768);
</script>
<Popover.Root>
  <Popover.Trigger
    class="rounded-input bg-dark
 text-background shadow-mini hover:bg-dark/95 inline-flex h-10 select-none items-center justify-center whitespace-nowrap px-[21px] text-[15px] font-medium transition-all hover:cursor-pointer active:scale-[0.98]"
  >
    Resize
  </Popover.Trigger>
  <Popover.Portal>
    <Popover.Content
      class="border-dark-10 bg-background shadow-popover data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-30 w-full max-w-[328px] rounded-[12px] border p-4"
      sideOffset={8}
    >
      <div class="flex items-center">
        <div
          class="bg-muted mr-3 flex size-12 items-center justify-center rounded-full"
        >
          <ImageSquare class="size-6" />
        </div>
        <div class="flex flex-col">
          <h4 class="text-[17px] font-semibold leading-5 tracking-[-0.01em]">
            Resize image
          </h4>
          <p class="text-muted-foreground text-sm font-medium">
            Resize your photos easily
          </p>
        </div>
      </div>
      <Separator.Root class="bg-dark-10 -mx-4 mb-6 mt-[17px] block h-px" />
      <div class="flex items-center pb-2">
        <div class="mr-2 flex items-center">
          <div class="relative mr-2">
            <span class="sr-only">Width</span>
            <span
              aria-hidden="true"
              class="text-xxs text-muted-foreground absolute left-5 top-4"
              >W</span
            >
            <input
              type="number"
              class="h-input rounded-10px border-border-input bg-background text-foreground w-[119px] border pl-10 pr-2 text-base sm:text-sm"
              bind:value={width}
            />
          </div>
          <div class="relative">
            <span class="sr-only">Height</span>
            <span
              aria-hidden="true"
              class="text-xxs text-muted-foreground absolute left-5 top-4"
              >H</span
            >
            <input
              type="number"
              class="h-input rounded-10px border-border-input bg-background text-foreground w-[119px] border pl-10 pr-2 text-base sm:text-sm"
              bind:value={height}
            />
          </div>
        </div>
        <Toggle.Root
          aria-label="toggle constrain portions"
          class="bg-background hover:bg-muted data-[state=on]:bg-muted inline-flex size-10 items-center justify-center rounded-[9px] transition-all active:scale-[0.98]"
        >
          <LinkSimpleHorizontalBreak class="size-6" />
        </Toggle.Root>
      </div>
    </Popover.Content>
  </Popover.Portal>
</Popover.Root>
```

## Structure

```svelte
<script lang="ts">
 import { Popover } from "bits-ui";
</script>
<Popover.Root>
 <Popover.Trigger />
 <Popover.Content>
  <Popover.Close />
  <Popover.Arrow />
 </Popover.Content>
</Popover.Root>
```

## Managing Open State

This section covers how to manage the `open` state of the component.

### Two-Way Binding

Use `bind:open` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { Popover } from "bits-ui";
 let isOpen = $state(false);
</script>
<button onclick={() => (isOpen = true)}>Open Popover</button>
<Popover.Root bind:open={isOpen}>
</Popover.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { Popover } from "bits-ui";
 let myOpen = $state(false);
 function getOpen() {
  return myOpen;
 }
 function setOpen(newOpen: boolean) {
  myOpen = newOpen;
 }
</script>
<Popover.Root bind:open={getOpen, setOpen}>
</Popover.Root>
```

## Managing Focus

### Focus Trap

By default, when a Popover is opened, focus will be trapped within that Popover. You can disable this behavior by setting the `trapFocus` prop to `false` on the `Popover.Content` component.

```svelte
<Popover.Content trapFocus={false}>
</Popover.Content>
```

### Open Focus

By default, when a Popover is opened, focus will be set to the first focusable element with the `Popover.Content`. This ensures that users navigating my keyboard end up somewhere within the Popover that they can interact with.

You can override this behavior using the `onOpenAutoFocus` prop on the `Popover.Content` component. It's *highly* recommended that you use this prop to focus *something* within the Popover's content.

You'll first need to cancel the default behavior of focusing the first focusable element by cancelling the event passed to the `onOpenAutoFocus` callback. You can then focus whatever you wish.

```svelte
<script lang="ts">
 import { Popover } from "bits-ui";
 let nameInput = $state<HTMLInputElement>();
</script>
<Popover.Root>
 <Popover.Trigger>Open Popover</Popover.Trigger>
 <Popover.Content
  onOpenAutoFocus={(e) => {
   e.preventDefault();
   nameInput?.focus();
  }}
 >
  <input type="text" bind:this={nameInput} />
 </Popover.Content>
</Popover.Root>
```

### Close Focus

By default, when a Popover is closed, focus will be set to the trigger element of the Popover. You can override this behavior using the `onCloseAutoFocus` prop on the `Popover.Content` component.

You'll need to cancel the default behavior of focusing the trigger element by cancelling the event passed to the `onCloseAutoFocus` callback, and then focus whatever you wish.

```svelte
<script lang="ts">
 import { Popover } from "bits-ui";
 let nameInput = $state<HTMLInputElement>();
</script>
<input type="text" bind:this={nameInput} />
<Popover.Root>
 <Popover.Trigger>Open Popover</Popover.Trigger>
 <Popover.Content
  onCloseAutoFocus={(e) => {
   e.preventDefault();
   nameInput?.focus();
  }}
 >
 </Popover.Content>
</Popover.Root>
```

## Scroll Lock

By default, when a Popover is opened, users can still scroll the body and interact with content outside of the Popover. If you wish to lock the body scroll and prevent users from interacting with content outside of the Popover, you can set the `preventScroll` prop to `true` on the `Popover.Content` component.

```svelte
<Popover.Content preventScroll={true}>
</Popover.Content>
```

## Escape Keydown

By default, when a Popover is open, pressing the `Escape` key will close the dialog. Bits UI provides a couple ways to override this behavior.

### escapeKeydownBehavior

You can set the `escapeKeydownBehavior` prop to `'ignore'` on the `Popover.Content` component to prevent the dialog from closing when the `Escape` key is pressed.

```svelte
<Popover.Content escapeKeydownBehavior="ignore">
</Popover.Content>
```

### onEscapeKeydown

You can also override the default behavior by cancelling the event passed to the `onEscapeKeydown` callback on the `Popover.Content` component.

```svelte
<Popover.Content onEscapeKeydown={(e) => e.preventDefault()}>
</Popover.Content>
```

## Interact Outside

By default, when a Popover is open, pointer down events outside the content will close the popover. Bits UI provides a couple ways to override this behavior.

### interactOutsideBehavior

You can set the `interactOutsideBehavior` prop to `'ignore'` on the `Popover.Content` component to prevent the dialog from closing when the user interacts outside the content.

```svelte
<Popover.Content interactOutsideBehavior="ignore">
</Popover.Content>
```

### onInteractOutside

You can also override the default behavior by cancelling the event passed to the `onInteractOutside` callback on the `Popover.Content` component.

```svelte
<Popover.Content onInteractOutside={(e) => e.preventDefault()}>
</Popover.Content>
```

## Custom Anchor

By default, the `Popover.Content` is anchored to the `Popover.Trigger` component, which determines where the content is positioned.

If you wish to instead anchor the content to a different element, you can pass either a selector `string` or an `HTMLElement` to the `customAnchor` prop of the `Popover.Content` component.

```svelte
<script lang="ts">
 import { Popover } from "bits-ui";
 let customAnchor = $state<HTMLElement>(null!);
</script>
<div bind:this={customAnchor}></div>
<Popover.Root>
 <Popover.Trigger />
 <Popover.Content {customAnchor}>
 </Popover.Content>
</Popover.Root>
```

## Svelte Transitions

You can use the `forceMount` prop along with the `child` snippet to forcefully mount the `Popover.Content` component to use Svelte Transitions or another animation library that requires more control.

```svelte
<script lang="ts">
 import { Popover } from "bits-ui";
 import { fly } from "svelte/transition";
</script>
<Popover.Content forceMount>
 {#snippet child({ wrapperProps, props, open })}
  {#if open}
   <div {...wrapperProps}>
    <div {...props} transition:fly>
    </div>
   </div>
  {/if}
 {/snippet}
</Popover.Content>
```

Of course, this isn't the prettiest syntax, so it's recommended to create your own reusable content component that handles this logic if you intend to use this approach. For more information on using transitions with Bits UI components, see the [Transitions](/docs/transitions) documentation.

```svelte
<script lang="ts">
  import { Popover, Separator, Toggle } from "bits-ui";
  import ImageSquare from "phosphor-svelte/lib/ImageSquare";
  import LinkSimpleHorizontalBreak from "phosphor-svelte/lib/LinkSimpleHorizontalBreak";
  import { fly } from "svelte/transition";
  let width = $state(1024);
  let height = $state(768);
</script>
<Popover.Root>
  <Popover.Trigger
    class="rounded-input bg-dark
 text-background shadow-mini hover:bg-dark/95 inline-flex h-10 select-none items-center justify-center whitespace-nowrap px-[21px] text-[15px] font-medium transition-all hover:cursor-pointer active:scale-[0.98]"
  >
    Resize
  </Popover.Trigger>
  <Popover.Portal>
    <Popover.Content
      class="border-dark-10 bg-background shadow-popover z-30 w-full max-w-[328px] rounded-[12px] border p-4"
      sideOffset={8}
      forceMount
    >
      {#snippet child({ wrapperProps, props, open })}
        {#if open}
          <div {...wrapperProps}>
            <div {...props} transition:fly={{ duration: 300 }}>
              <div class="flex items-center">
                <div
                  class="bg-muted mr-3 flex size-12 items-center justify-center rounded-full"
                >
                  <ImageSquare class="size-6" />
                </div>
                <div class="flex flex-col">
                  <h4
                    class="text-[17px] font-semibold leading-5 tracking-[-0.01em]"
                  >
                    Resize image
                  </h4>
                  <p class="text-muted-foreground text-sm font-medium">
                    Resize your photos easily
                  </p>
                </div>
              </div>
              <Separator.Root
                class="bg-dark-10 -mx-4 mb-6 mt-[17px] block h-px"
              />
              <div class="flex items-center pb-2">
                <div class="mr-2 flex items-center">
                  <div class="relative mr-2">
                    <span class="sr-only">Width</span>
                    <span
                      aria-hidden="true"
                      class="text-xxs text-muted-foreground absolute left-5 top-4"
                      >W</span
                    >
                    <input
                      type="number"
                      class="h-input rounded-10px border-border-input bg-background text-foreground w-[119px] border pl-10 pr-2 text-base sm:text-sm"
                      bind:value={width}
                    />
                  </div>
                  <div class="relative">
                    <span class="sr-only">Height</span>
                    <span
                      aria-hidden="true"
                      class="text-xxs text-muted-foreground absolute left-5 top-4"
                      >H</span
                    >
                    <input
                      type="number"
                      class="h-input rounded-10px border-border-input bg-background text-foreground w-[119px] border pl-10 pr-2 text-base sm:text-sm"
                      bind:value={height}
                    />
                  </div>
                </div>
                <Toggle.Root
                  aria-label="toggle constrain portions"
                  class="bg-background hover:bg-muted data-[state=on]:bg-muted inline-flex size-10 items-center justify-center rounded-[9px] transition-all active:scale-[0.98]"
                >
                  <LinkSimpleHorizontalBreak class="size-6" />
                </Toggle.Root>
              </div>
            </div>
          </div>
        {/if}
      {/snippet}
    </Popover.Content>
  </Popover.Portal>
</Popover.Root>
```

## API Reference

### Popover.Root

The root component used to manage the state of the state of the popover.

| Property                                                                                     | Type                                                                                                                                                                                                           | Description                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `open` $bindable | `boolean`                                                                                                                                                           | The open state of the link popover component.`Default: false`                               |
| `onOpenChange`                                             | `function`- (open: boolean) => void | A callback that fires when the open state changes.`Default:  undefined`                  |
| `children`                                                 | `Snippet`                                                                                                                                                           | The children content to render.`Default:  undefined` |

### Popover.Trigger

A component which toggles the opening and closing of the popover on press.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                        |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | Whether the popover is open or closed.                                      |
| `data-popover-trigger`                            | `''`                                                                                                                                                                                 | Present on the trigger element. |

### Popover.Content

The contents of the popover which are displayed when the popover is open.

| Property                                                              | Type                                                                                                                                                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `side` | `enum`- 'top' \| 'bottom' \| 'left' \| 'right'                                     | The preferred side of the anchor to render the floating element against when open. Will be reversed when collisions occur.`Default: bottom`                                                                                                                                                                                                                                                                                        |
| `sideOffset`                        | `number`                                                                                                                                                                                                           | The distance in pixels from the anchor to the floating element.`Default: 0`                                                                                                                                                                                                                                                                                                                                                        |
| `align`                             | `enum`- 'start' \| 'center' \| 'end'                                               | The preferred alignment of the anchor to render the floating element against when open. This may change when collisions occur.`Default: start`                                                                                                                                                                                                                                                                                     |
| `alignOffset`                       | `number`                                                                                                                                                                                                           | The distance in pixels from the anchor to the floating element.`Default: 0`                                                                                                                                                                                                                                                                                                                                                        |
| `arrowPadding`                      | `number`                                                                                                                                                                                                           | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0`                                                                                                                                                                                                                                                                                                  |
| `avoidCollisions`                   | `boolean`                                                                                                                                                                                                          | When `true`, overrides the `side` and `align` options to prevent collisions with the boundary edges.`Default: true`                                                                                                                                                                                                                                                                                                                |
| `collisionBoundary`                 | `union`- Element \| null                                                           | A boundary element or array of elements to check for collisions against.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                   |
| `collisionPadding`                  | `union`- number \| Partial\&lt;Record\&lt;Side, number\&gt;\&gt;                   | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0`                                                                                                                                                                                                                                                                                                  |
| `sticky`                            | `enum`- 'partial' \| 'always'                                                      | The sticky behavior on the align axis. `'partial'` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst `'always'` will keep the content in the boundary regardless.`Default: partial`                                                                                                                                                                                        |
| `hideWhenDetached`                  | `boolean`                                                                                                                                                                                                          | When `true`, hides the content when it is detached from the DOM. This is useful for when you want to hide the content when the user scrolls away.`Default: true`                                                                                                                                                                                                                                                                   |
| `updatePositionStrategy`            | `enum`- 'optimized' \| 'always'                                                    | The strategy to use when updating the position of the content. When `'optimized'` the content will only be repositioned when the trigger is in the viewport. When `'always'` the content will be repositioned whenever the position changes.`Default: optimized`                                                                                                                                                                   |
| `strategy`                          | `enum`- 'fixed' \| 'absolute'                                                      | The positioning strategy to use for the floating element. When `'fixed'` the element will be positioned relative to the viewport. When `'absolute'` the element will be positioned relative to the nearest positioned ancestor.`Default: fixed`                                                                                                                                                                                    |
| `preventScroll`                     | `boolean`                                                                                                                                                                                                          | When `true`, prevents the body from scrolling when the content is open. This is useful when you want to use the content as a modal.`Default: false`                                                                                                                                                                                                                                                                                |
| `customAnchor`                      | `union`- string \| HTMLElement \| Measurable \| null                               | Use an element other than the trigger to anchor the content to. If provided, the content will be anchored to the provided element instead of the trigger.`Default: null`                                                                                                                                                                                                                                                           |
| `onInteractOutside`                 | `function`- (event: PointerEvent) => void                                          | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default:  undefined`                                                                                                                                                                                                        |
| `onFocusOutside`                    | `function`- (event: FocusEvent) => void                                            | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default:  undefined`                                                                                                                                                                                                                                                  |
| `interactOutsideBehavior`           | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close`  |
| `onEscapeKeydown`                   | `function`- (event: KeyboardEvent) => void                                         | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default:  undefined`                                                                                                                                                                                                                    |
| `escapeKeydownBehavior`             | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` |
| `onOpenAutoFocus`                   | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is opened. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `onCloseAutoFocus`                  | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is closed. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `trapFocus`                         | `boolean`                                                                                                                                                                                                          | Whether or not to trap the focus within the content when open.`Default: true`                                                                                                                                                                                                                                                                                                                                                      |
| `preventOverflowTextSelection`      | `boolean`                                                                                                                                                                                                          | When `true`, prevents the text selection from overflowing the bounds of the element.`Default: true`                                                                                                                                                                                                                                                                                                                                |
| `forceMount`                        | `boolean`                                                                                                                                                                                                          | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                                                                                                                                                                                                                                                                 |
| `dir`                               | `enum`- 'ltr' \| 'rtl'                                                             | The reading direction of the app.`Default: 'ltr'`                                                                                                                                                                                                                                                                                                                                                                                  |
| `ref` $bindable        | `HTMLDivElement`                                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                                                                                                                                                                         |
| `children`                          | `Snippet`                                                                                                                                                                                                          | The children content to render.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                                                            |
| `child`                             | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };               | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                                                                                                                                                                  | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                        |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | Whether the popover is open or closed.                                      |
| `data-popover-content`                            | `''`                                                                                                                                                                                 | Present on the content element. |

| CSS Variable                                                            | Description                                                                                                   |
| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--bits-popover-content-transform-origin` | The transform origin of the popover content element.                                   |
| `--bits-popover-content-available-width`                                       | The available width of the popover content element.                                    |
| `--bits-popover-content-available-height`                                      | The available height of the popover content element.                                   |
| `--bits-popover-anchor-width`                                                  | The width of the popover trigger element.                                              |
| `--bits-popover-anchor-height`                                                 | The height of the popover trigger element. |

### Popover.ContentStatic

The contents of the popover which are displayed when the popover is open. (Static/No Floating UI)

| Property                                                                           | Type                                                                                                                                                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onInteractOutside` | `function`- (event: PointerEvent) => void                                          | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default:  undefined`                                                                                                                                                                                                        |
| `onFocusOutside`                                 | `function`- (event: FocusEvent) => void                                            | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default:  undefined`                                                                                                                                                                                                                                                  |
| `interactOutsideBehavior`                        | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close`  |
| `onEscapeKeydown`                                | `function`- (event: KeyboardEvent) => void                                         | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default:  undefined`                                                                                                                                                                                                                    |
| `escapeKeydownBehavior`                          | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` |
| `onOpenAutoFocus`                                | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is opened. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `onCloseAutoFocus`                               | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is closed. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `trapFocus`                                      | `boolean`                                                                                                                                                                                                          | Whether or not to trap the focus within the content when open.`Default: true`                                                                                                                                                                                                                                                                                                                                                      |
| `preventOverflowTextSelection`                   | `boolean`                                                                                                                                                                                                          | When `true`, prevents the text selection from overflowing the bounds of the element.`Default: true`                                                                                                                                                                                                                                                                                                                                |
| `preventScroll`                                  | `boolean`                                                                                                                                                                                                          | When `true`, prevents the body from scrolling when the content is open. This is useful when you want to use the content as a modal.`Default: false`                                                                                                                                                                                                                                                                                |
| `forceMount`                                     | `boolean`                                                                                                                                                                                                          | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                                                                                                                                                                                                                                                                 |
| `dir`                                            | `enum`- 'ltr' \| 'rtl'                                                             | The reading direction of the app.`Default: 'ltr'`                                                                                                                                                                                                                                                                                                                                                                                  |
| `ref` $bindable                     | `HTMLDivElement`                                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                                                                                                                                                                         |
| `children`                                       | `Snippet`                                                                                                                                                                                                          | The children content to render.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                                                            |
| `child`                                          | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };               | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                                                                                                                                                                  | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                        |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | Whether the popover is open or closed.                                      |
| `data-popover-content`                            | `''`                                                                                                                                                                                 | Present on the content element. |

### Popover.Close

A button which closes the popover when pressed and is typically placed in the content.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                     | Value         | Description                                                                                     |
| ------------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-popover-close` | `''` | Present on the close button. |

### Popover.Arrow

An optional arrow element which points to the trigger when the popover is open.

| Property                                                               | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `width` | `number`                                                                                                                                                                                             | The width of the arrow in pixels.`Default: 8`                                                                                                                                     |
| `height`                             | `number`                                                                                                                                                                                             | The height of the arrow in pixels.`Default: 8`                                                                                                                                    |
| `ref` $bindable         | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                           | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                              | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value         | Description                                                                                      |
| ----------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-arrow` | `''` | Present on the arrow element.                                             |
| `data-popover-arrow`                              | `''` | Present on the arrow element. |

----------------------------------------------------

# Progress Documentation

Visualizes the progress or completion status of a task or process.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { Progress, useId } from "bits-ui";
  import { onMount } from "svelte";
  let value = $state(13);
  const labelId = useId();
  onMount(() => {
    const timer = setTimeout(() => (value = 66), 500);
    return () => clearTimeout(timer);
  });
</script>
<div class="flex w-[60%] flex-col gap-2">
  <div class="flex items-center justify-between text-sm font-medium">
    <span id={labelId}> Uploading file... </span>
    <span>{value}%</span>
  </div>
  <Progress.Root
    aria-labelledby={labelId}
    {value}
    max={100}
    class="bg-dark-10 shadow-mini-inset relative h-[15px] w-full overflow-hidden rounded-full"
  >
    <div
      class="bg-foreground shadow-mini-inset h-full w-full flex-1 rounded-full transition-all duration-1000 ease-in-out"
      style={`transform: translateX(-${100 - (100 * (value ?? 0)) / 100}%)`} ></div>
  </Progress.Root>
</div>
```

While often visually similar, progress bars and [Meters](/docs/components/meter) serve distinct purposes:

**Progress**:

- Shows **completion status** of a task  
- Value only increases as task progresses  
- Examples: File upload, installation status, form completion  
- Use when tracking advancement toward completion **Meter**:

- Displays a **static measurement** within a known range (0-100)  
- Value can fluctuate up/down based on real-time measurements  
- Examples: CPU usage, battery level, sound volume  
- Use when showing current state relative to capacity If a meter better fits your requirements, check out the [Meter](/docs/components/meter) component.

## Structure

```svelte
<script lang="ts">
 import { Progress } from "bits-ui";
</script>
<Progress.Root />
```

## Reusable Components

It's recommended to use the `Progress` primitive to create your own custom meter component that can be used throughout your application. In the example below, we're using the `Progress` primitive to create a more comprehensive meter component.

```svelte
<script lang="ts">
 import { Progress, useId } from "bits-ui";
 import type { ComponentProps } from "svelte";
 let {
  max = 100,
  value = 0,
  min = 0,
  label,
  valueLabel,
 }: ComponentProps<typeof Progress.Root> & {
  label: string;
  valueLabel: string;
 } = $props();
 const labelId = useId();
</script>
<div>
 <span id={labelId}> {label} </span>
 <span>{valueLabel}</span>
</div>
<Progress.Root aria-labelledby={labelId} aria-valuetext={valueLabel} {value} {min} {max} />
```

You can then use the `MyProgress` component in your application like so:

+page.svelte

```svelte
<script lang="ts">
 import MyProgress from "$lib/components/MyProgress.svelte";
 let value = $state(50);
</script>
<MyProgress label="Loading images..." valueLabel="{value}%" {value} />
```

Of course, you'd want to apply your own styles and other customizations to the `MyProgress` component to fit your application's design.

## Accessibility

If a visual label is used, the ID of the label element should be pass via the `aria-labelledby` prop to `Progress.Root`. If no visual label is used, the `aria-label` prop should be used to provide a text description of the progress bar.

## API Reference

### Progress.Root

The progress bar component.

| Property                                                             | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `max` | `number`                                                                                                                                                                                             | The maximum value of the progress bar.`Default: 100`                                                                                                                              |
| `min`                              | `number`                                                                                                                                                                                             | The minimum value of the progress bar.`Default: 0`                                                                                                                                |
| `value`                            | `number \| null`                                                                                                                                                                                     | The current value of the progress bar. If set to `null``Default: 0`                                                                                                               |
| `ref` $bindable       | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                         | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                            | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value                                                                                                                                                                         | Description                                                                                     |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-value` | `''`                                                                                                                                                                 | The current value of the progress bar.                                   |
| `data-state`                                      | `enum`- '' | The current state of the progress bar.                                   |
| `data-min`                                        | `''`                                                                                                                                                                 | The minimum value of the progress bar.                                   |
| `data-max`                                        | `''`                                                                                                                                                                 | The maximum value of the progress bar.                                   |
| `data-indeterminate`                              | `''`                                                                                                                                                                 | Present when the value is `null`.                                        |
| `data-progress-root`                              | `''`                                                                                                                                                                 | Present on the root element. |

----------------------------------------------------

# Radio Group Documentation

Allows users to select a single option from a list of mutually exclusive choices.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { Label, RadioGroup } from "bits-ui";
</script>
<RadioGroup.Root class="flex flex-col gap-4 text-sm font-medium">
  <div
    class="text-foreground group flex select-none items-center transition-all"
  >
    <RadioGroup.Item
      id="amazing"
      value="amazing"
      class="border-border-input bg-background hover:border-dark-40 data-[state=checked]:border-6 data-[state=checked]:border-foreground size-5 shrink-0 cursor-default rounded-full border transition-all duration-100 ease-in-out"
    />
    <Label.Root for="amazing" class="pl-3">Amazing</Label.Root>
  </div>
  <div
    class="text-foreground group flex select-none items-center transition-all"
  >
    <RadioGroup.Item
      id="average"
      value="average"
      class="border-border-input bg-background hover:border-dark-40 data-[state=checked]:border-6 data-[state=checked]:border-foreground size-5 shrink-0 cursor-default rounded-full border transition-all duration-100 ease-in-out"
    />
    <Label.Root for="average" class="pl-3">Average</Label.Root>
  </div>
  <div
    class="text-foreground group flex select-none items-center transition-all"
  >
    <RadioGroup.Item
      id="terrible"
      value="terrible"
      class="border-border-input bg-background hover:border-dark-40 data-[state=checked]:border-6 data-[state=checked]:border-foreground size-5 shrink-0 cursor-default rounded-full border transition-all duration-100 ease-in-out"
    />
    <Label.Root for="terrible" class="pl-3">Terrible</Label.Root>
  </div>
</RadioGroup.Root>
```

## Structure

```svelte
<script lang="ts">
 import { RadioGroup } from "bits-ui";
</script>
<RadioGroup.Root>
 <RadioGroup.Item>
  {#snippet children({ checked })}
   {#if checked}
    
   {/if}
  {/snippet}
 </RadioGroup.Item>
</RadioGroup.Root>
```

## Reusable Components

It's recommended to use the `RadioGroup` primitives to create your own custom components that can be used throughout your application.

In the example below, we're creating a custom `MyRadioGroup` component that takes in an array of items and renders a radio group with those items along with a [`Label`](/docs/components/label) component for each item.

MyRadioGroup.svelte

```svelte
<script lang="ts">
 import { RadioGroup, Label, type WithoutChildrenOrChild, useId } from "bits-ui";
 type Item = {
  value: string;
  label: string;
  disabled?: boolean;
 };
 type Props = WithoutChildrenOrChild<RadioGroup.RootProps> & {
  items: Item[];
 };
 let { value = $bindable(""), ref = $bindable(null), items, ...restProps }: Props = $props();
</script>
<RadioGroup.Root bind:value bind:ref {...restProps}>
 {#each items as item}
  {@const id = useId()}
  <div>
   <RadioGroup.Item {id} value={item.value} disabled={item.disabled}>
    {#snippet children({ checked })}
     {#if checked}
      
     {/if}
    {/snippet}
   </RadioGroup.Item>
   <Label.Root for={id}>{item.label}</Label.Root>
  </div>
 {/each}
</RadioGroup.Root>
```

You can then use the `MyRadioGroup` component in your application like so:

+page.svelte

```svelte
<script lang="ts">
 import MyRadioGroup from "$lib/components/MyRadioGroup.svelte";
 const myItems = [
  { value: "apple", label: "Apple" },
  { value: "banana", label: "Banana" },
  { value: "coconut", label: "Coconut", disabled: true },
 ];
</script>
<MyRadioGroup items={myItems} name="favoriteFruit" />
```

## Managing Value State

This section covers how to manage the `value` state of the component.

### Two-Way Binding

Use `bind:value` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { RadioGroup } from "bits-ui";
 let myValue = $state("");
</script>
<button onclick={() => (myValue = "A")}> Select A </button>
<RadioGroup.Root bind:value={myValue}>
</RadioGroup.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { RadioGroup } from "bits-ui";
 let myValue = $state("");
 function getValue() {
  return myValue;
 }
 function setValue(newValue: string) {
  myValue = newValue;
 }
</script>
<RadioGroup.Root bind:value={getValue, setValue}>
</RadioGroup.Root>
```

## HTML Forms

If you set the `name` prop on the `RadioGroup.Root` component, a hidden input element will be rendered to submit the value of the radio group to a form.

```svelte
<RadioGroup.Root name="favoriteFruit">
</RadioGroup.Root>
```

### Required

To make the hidden input element `required` you can set the `required` prop on the `RadioGroup.Root` component.

```svelte
<RadioGroup.Root required>
</RadioGroup.Root>
```

## Disabling Items

You can disable a radio group item by setting the `disabled` prop to `true`.

```svelte
<RadioGroup.Item value="apple" disabled>Apple</RadioGroup.Item>
```

## Orientation

The `orientation` prop is used to determine the orientation of the radio group, which influences how keyboard navigation will work.

When the `orientation` is set to `'vertical'`, the radio group will navigate through the items using the `ArrowUp` and `ArrowDown` keys. When the `orientation` is set to `'horizontal'`, the radio group will navigate through the items using the `ArrowLeft` and `ArrowRight` keys.

```svelte
<RadioGroup.Root orientation="vertical">
</RadioGroup.Root>
<RadioGroup.Root orientation="horizontal">
</RadioGroup.Root>
```

## API Reference

### RadioGroup.Root

The radio group component used to group radio items under a common name for form submission.

| Property                                                                                      | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` $bindable | `string`                                                                                                                                                                                             | The value of the currently selected radio item. You can bind to this value to control the radio group's value from outside the component.`Default:  undefined`                 |
| `onValueChange`                                             | `function`- (value: string) => void                                  | A callback that is fired when the radio group's value changes.`Default:  undefined`                                                                                            |
| `disabled`                                                  | `boolean`                                                                                                                                                                                            | Whether or not the radio group is disabled. This prevents the user from interacting with it.`Default: false`                                                                      |
| `required`                                                  | `boolean`                                                                                                                                                                                            | Whether or not the radio group is required.`Default: false`                                                                                                                       |
| `name`                                                      | `string`                                                                                                                                                                                             | The name of the radio group used in form submission. If provided, a hidden input element will be rendered to submit the value of the radio group.`Default:  undefined`         |
| `loop`                                                      | `boolean`                                                                                                                                                                                            | Whether or not the radio group should loop through the items when navigating with the arrow keys.`Default: false`                                                                 |
| `orientation`                                               | `enum`- 'vertical' \| 'horizontal'                                   | The orientation of the radio group. This will determine how keyboard navigation will work within the component.`Default: 'vertical'`                                              |
| `ref` $bindable                                | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                  | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                     | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                   | Value                                                                                                                                                                         | Description                                                                                     |
| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-orientation` | `enum`- '' | The orientation of the radio group.                                      |
| `data-radio-group-root`                                 | `''`                                                                                                                                                                 | Present on the root element. |

### RadioGroup.Item

An radio item, which must be a child of the `RadioGroup.Root` component.

| Property                                                                                     | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` required | `string`                                                                                                                                                                                             | The value of the radio item. This should be unique for each radio item in the group.`Default:  undefined`                                                                      |
| `disabled`                                                 | `boolean`                                                                                                                                                                                            | Whether the radio item is disabled.`Default: false`                                                                                                                               |
| `ref` $bindable                               | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                 | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                    | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value                                                                                                                                                                         | Description                                                                                           |
| -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''`                                                                                                                                                                 | Present when the radio item is disabled.                                       |
| `data-value`                                         | `''`                                                                                                                                                                 | The value of the radio item.                                                   |
| `data-state`                                         | `enum`- '' | The radio item's checked state.                                                |
| `data-orientation`                                   | `enum`- '' | The orientation of the parent radio group.                                     |
| `data-radio-group-item`                              | `''`                                                                                                                                                                 | Present on the radio item element. |

----------------------------------------------------

# Range Calendar Documentation

Presents a calendar view tailored for selecting date ranges.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { RangeCalendar } from "bits-ui";
  import CaretLeft from "phosphor-svelte/lib/CaretLeft";
  import CaretRight from "phosphor-svelte/lib/CaretRight";
  import { cn } from "$lib/utils/styles.js";
  import type { ComponentProps } from "svelte";
  let { value = $bindable() }: ComponentProps<typeof RangeCalendar.Root> =
    $props();
</script>
<RangeCalendar.Root
  class="rounded-15px border-dark-10 bg-background-alt shadow-card mt-6 border p-[22px]"
  weekdayFormat="short"
  fixedWeeks={true}
  bind:value
>
  {#snippet children({ months, weekdays })}
    <RangeCalendar.Header class="flex items-center justify-between">
      <RangeCalendar.PrevButton
        class="rounded-9px bg-background-alt hover:bg-muted inline-flex size-10 items-center justify-center active:scale-[0.98]"
      >
        <CaretLeft class="size-6" />
      </RangeCalendar.PrevButton>
      <RangeCalendar.Heading class="text-[15px] font-medium" />
      <RangeCalendar.NextButton
        class="rounded-9px bg-background-alt hover:bg-muted inline-flex size-10 items-center justify-center active:scale-[0.98]"
      >
        <CaretRight class="size-6" />
      </RangeCalendar.NextButton>
    </RangeCalendar.Header>
    <div
      class="flex flex-col space-y-4 pt-4 sm:flex-row sm:space-x-4 sm:space-y-0"
    >
      {#each months as month}
        <RangeCalendar.Grid
          class="w-full border-collapse select-none space-y-1"
        >
          <RangeCalendar.GridHead>
            <RangeCalendar.GridRow class="mb-1 flex w-full justify-between">
              {#each weekdays as day}
                <RangeCalendar.HeadCell
                  class="text-muted-foreground font-normal! w-10 rounded-md text-xs"
                >
                  <div>{day.slice(0, 2)}</div>
                </RangeCalendar.HeadCell>
              {/each}
            </RangeCalendar.GridRow>
          </RangeCalendar.GridHead>
          <RangeCalendar.GridBody>
            {#each month.weeks as weekDates}
              <RangeCalendar.GridRow class="flex w-full">
                {#each weekDates as date}
                  <RangeCalendar.Cell
                    {date}
                    month={month.value}
                    class="p-0! relative m-0 size-10 text-center text-sm focus-within:z-20"
                  >
                    <RangeCalendar.Day
                      class={cn(
                        "rounded-9px text-foreground hover:border-foreground focus-visible:ring-foreground! data-selection-end:rounded-9px data-selection-start:rounded-9px data-highlighted:bg-muted data-selected:bg-muted data-selection-end:bg-foreground data-selection-start:bg-foreground data-disabled:text-foreground/30 data-selected:text-foreground data-selection-end:text-background data-selection-start:text-background data-unavailable:text-muted-foreground data-selected:[&:not([data-selection-start])]:[&:not([data-selection-end])]:focus-visible:border-foreground data-disabled:pointer-events-none data-outside-month:pointer-events-none data-highlighted:rounded-none data-selected:font-medium data-selection-end:font-medium data-selection-start:font-medium data-unavailable:line-through data-selection-start:focus-visible:ring-2 data-selection-start:focus-visible:ring-offset-2! data-selected:[&:not([data-selection-start])]:[&:not([data-selection-end])]:rounded-none data-selected:[&:not([data-selection-start])]:[&:not([data-selection-end])]:focus-visible:ring-0! data-selected:[&:not([data-selection-start])]:[&:not([data-selection-end])]:focus-visible:ring-offset-0! group relative inline-flex size-10 items-center justify-center overflow-visible whitespace-nowrap border border-transparent bg-transparent p-0 text-sm font-normal"
                      )}
                    >
                      <div
                        class="bg-foreground group-data-selected:bg-background group-data-today:block absolute top-[5px] hidden size-1 rounded-full"
                      ></div>
                      {date.day}
                    </RangeCalendar.Day>
                  </RangeCalendar.Cell>
                {/each}
              </RangeCalendar.GridRow>
            {/each}
          </RangeCalendar.GridBody>
        </RangeCalendar.Grid>
      {/each}
    </div>
  {/snippet}
</RangeCalendar.Root>
```

##### Heads up!

Before diving into this component, it's important to understand how dates/times work in Bits UI. Please read the [Dates](/docs/dates) documentation to learn more!

## Structure

```svelte
<script lang="ts">
 import { RangeCalendar } from "bits-ui";
</script>
<RangeCalendar.Root>
 {#snippet children({ months, weekdays })}
  <RangeCalendar.Header>
   <RangeCalendar.PrevButton />
   <RangeCalendar.Heading />
   <RangeCalendar.NextButton />
  </RangeCalendar.Header>
  {#each months as month}
   <RangeCalendar.Grid>
    <RangeCalendar.GridHead>
     <RangeCalendar.GridRow>
      {#each weekdays as day}
       <RangeCalendar.HeadCell>
        {day}
       </RangeCalendar.HeadCell>
      {/each}
     </RangeCalendar.GridRow>
    </RangeCalendar.GridHead>
    <RangeCalendar.GridBody>
     {#each month.weeks as weekDates}
      <RangeCalendar.GridRow>
       {#each weekDates as date}
        <RangeCalendar.Cell {date} month={month.value}>
         <RangeCalendar.Day />
        </RangeCalendar.Cell>
       {/each}
      </RangeCalendar.GridRow>
     {/each}
    </RangeCalendar.GridBody>
   </RangeCalendar.Grid>
  {/each}
 {/snippet}
</RangeCalendar.Root>
```

## API Reference

### RangeCalendar.Root

The root range calendar component which contains all other calendar components.

| Property                                                                                      | Type                                                                                                                                                                                                                                                                                                                                                     | Description                                                                                                                                                                                                                                                              |
| -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `value` $bindable | `DateRange`- import type { DateValue } from "@internationalized/date"; type DateRange = { start: DateValue \| undefined; end: DateValue \| undefined; };                      | The selected date range.`Default:  undefined`                                                                                                                                                                                           |
| `onValueChange`                                             | `function`- (range: DateRange) => void                                                                                                                                        | A function that is called when the selected date range changes.`Default:  undefined`                                                                                                                                                    |
| `placeholder`                                               | `DateValue`- import type { CalendarDate, CalendarDateTime, ZonedDateTime } from "@internationalized/date"; type DateValue = CalendarDate \| CalendarDateTime \| ZonedDateTime | The placeholder date, which is used to determine what month to display when no date is selected. This updates as the user navigates the calendar, and can be used to programmatically control the calendar's view.`Default:  undefined` |
| `onPlaceholderChange`                                       | `function`- (date: DateValue) => void                                                                                                                                         | A function that is called when the placeholder date changes.`Default:  undefined`                                                                                                                                                       |
| `pagedNavigation`                                           | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not to use paged navigation for the calendar. Paged navigation causes the previous and next buttons to navigate by the number of months displayed at once, rather than by one month.`Default: false`                            |
| `preventDeselect`                                           | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not to prevent the user from deselecting a date without selecting another date first.`Default: false`                                                                                                                           |
| `weekdayFormat`                                             | `enum`- 'narrow' \| 'short' \| 'long'                                                                                                                                         | The format to use for the weekday strings provided via the `weekdays` slot prop.`Default: 'narrow'`                                                                                                                                        |
| `weekStartsOn`                                              | `number`                                                                                                                                                                                                                                                                                                      | The day of the week to start the calendar on. 0 is Sunday, 1 is Monday, etc.`Default: 0`                                                                                                                                                   |
| `calendarLabel`                                             | `string`                                                                                                                                                                                                                                                                                                      | The accessible label for the calendar.`Default:  undefined`                                                                                                                                                                             |
| `fixedWeeks`                                                | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not to always display 6 weeks in the calendar.`Default: false`                                                                                                                                                                  |
| `isDateDisabled`                                            | `function`- (date: DateValue) => boolean                                                                                                                                      | A function that returns whether or not a date is disabled.`Default:  undefined`                                                                                                                                                         |
| `isDateUnavailable`                                         | `function`- (date: DateValue) => boolean                                                                                                                                      | A function that returns whether or not a date is unavailable.`Default:  undefined`                                                                                                                                                      |
| `maxValue`                                                  | `DateValue`- import type { CalendarDate, CalendarDateTime, ZonedDateTime } from "@internationalized/date"; type DateValue = CalendarDate \| CalendarDateTime \| ZonedDateTime | The maximum date that can be selected.`Default:  undefined`                                                                                                                                                                             |
| `minValue`                                                  | `DateValue`- import type { CalendarDate, CalendarDateTime, ZonedDateTime } from "@internationalized/date"; type DateValue = CalendarDate \| CalendarDateTime \| ZonedDateTime | The minimum date that can be selected.`Default:  undefined`                                                                                                                                                                             |
| `locale`                                                    | `string`                                                                                                                                                                                                                                                                                                      | The locale to use for formatting dates.`Default: 'en'`                                                                                                                                                                                     |
| `numberOfMonths`                                            | `number`                                                                                                                                                                                                                                                                                                      | The number of months to display at once.`Default: 1`                                                                                                                                                                                       |
| `disabled`                                                  | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not the accordion is disabled.`Default: false`                                                                                                                                                                                  |
| `readonly`                                                  | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not the calendar is readonly.`Default: false`                                                                                                                                                                                   |
| `disableDaysOutsideMonth`                                   | `boolean`                                                                                                                                                                                                                                                                                                     | Whether or not to disable days outside the current month.`Default: false`                                                                                                                                                                  |
| `onStartValueChange`                                        | `function`- (value: DateValue) => void                                                                                                                                        | A function that is called when the start date changes.`Default:  undefined`                                                                                                                                                             |
| `onEndValueChange`                                          | `function`- (value: DateValue) => void                                                                                                                                        | A function that is called when the end date changes.`Default:  undefined`                                                                                                                                                               |
| `ref` $bindable                                | `HTMLDivElement`                                                                                                                                                                                                                                                                                              | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                 |
| `children`                                                  | `Snippet`                                                                                                                                                                                                                                                                                                     | The children content to render.`Default:  undefined`                                                                                                                                                                                    |
| `child`                                                     | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };                                                                                                          | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                          | | Data Attribute                               | Value         | Description                                                                                     |
| ------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-invalid` | `''` | Present on the root element when the calendar is invalid.                |
| `data-disabled`                                     | `''` | Present on the root element when the calendar is disabled.               |
| `data-readonly`                                     | `''` | Present on the root element when the calendar is readonly.               |
| `data-calendar-root`                                | `''` | Present on the root element. |

### RangeCalendar.Header

The header of the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLElement`                                                                                                                                                                                        | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                       |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the header element when the calendar is disabled.               |
| `data-readonly`                                      | `''` | Present on the header element when the calendar is readonly.               |
| `data-calendar-header`                               | `''` | Present on the header element. |

### RangeCalendar.Heading

The heading of the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                        |
| -------------------------------------------------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the heading element when the calendar is disabled.               |
| `data-readonly`                                      | `''` | Present on the heading element when the calendar is readonly.               |
| `data-calendar-heading`                              | `''` | Present on the heading element. |

### RangeCalendar.NextButton

The next button of the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                             |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the next button element when the calendar or this button is disabled. |
| `data-calendar-next-button`                          | `''` | Present on the next button element.  |

### RangeCalendar.PrevButton

The previous button of the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                             |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the prev button element when the calendar or this button is disabled. |
| `data-calendar-prev-button`                          | `''` | Present on the prev button element.  |

### RangeCalendar.Cell

A cell in the calendar grid.

| Property                                                              | Type                                                                                                                                                                                                                                                                                                                                                     | Description                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `date` | `DateValue`- import type { CalendarDate, CalendarDateTime, ZonedDateTime } from "@internationalized/date"; type DateValue = CalendarDate \| CalendarDateTime \| ZonedDateTime | The date for the cell.`Default:  undefined`                                                                                                                                    |
| `month`                             | `DateValue`- import type { CalendarDate, CalendarDateTime, ZonedDateTime } from "@internationalized/date"; type DateValue = CalendarDate \| CalendarDateTime \| ZonedDateTime | The current month the date is being displayed in.`Default:  undefined`                                                                                                         |
| `ref` $bindable        | `HTMLTableCellElement`                                                                                                                                                                                                                                                                                        | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                          | `Snippet`                                                                                                                                                                                                                                                                                                     | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                             | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };                                                                                                          | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                                             |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present when the day is disabled.                                                                |
| `data-unavailable`                                   | `''` | Present when the day is unavailable.                                                             |
| `data-today`                                         | `''` | Present when the day is today.                                                                   |
| `data-outside-month`                                 | `''` | Present when the day is outside the current month.                                               |
| `data-outside-visible-months`                        | `''` | Present when the day is outside the visible months.                                              |
| `data-focused`                                       | `''` | Present when the day is focused.                                                                 |
| `data-selected`                                      | `''` | Present when the day is selected.                                                                |
| `data-value`                                         | `''` | The date in the format "YYYY-MM-DD".                                                             |
| `data-calendar-cell`                                 | `''` | Present on the cell element.                                                                     |
| `data-selection-start`                               | `''` | Present when the cell is the start of a selection.                                               |
| `data-selection-end`                                 | `''` | Present when the cell is the end of a selection.                                                 |
| `data-highlighted`                                   | `''` | Present when the cell is highlighted within a range. |

### RangeCalendar.Day

A day in the calendar grid.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                                             |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present when the day is disabled.                                                                |
| `data-unavailable`                                   | `''` | Present when the day is unavailable.                                                             |
| `data-today`                                         | `''` | Present when the day is today.                                                                   |
| `data-outside-month`                                 | `''` | Present when the day is outside the current month.                                               |
| `data-outside-visible-months`                        | `''` | Present when the day is outside the visible months.                                              |
| `data-focused`                                       | `''` | Present when the day is focused.                                                                 |
| `data-selected`                                      | `''` | Present when the day is selected.                                                                |
| `data-value`                                         | `''` | The date in the format "YYYY-MM-DD".                                                             |
| `data-calendar-cell`                                 | `''` | Present on the cell element.                                                                     |
| `data-selection-start`                               | `''` | Present when the cell is the start of a selection.                                               |
| `data-selection-end`                                 | `''` | Present when the cell is the end of a selection.                                                 |
| `data-highlighted`                                   | `''` | Present when the cell is highlighted within a range. |

### RangeCalendar.Grid

The grid of dates in the calendar, typically representing a month.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLTableElement`                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                     |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the grid element when the calendar is disabled.               |
| `data-readonly`                                      | `''` | Present on the grid element when the calendar is readonly.               |
| `data-calendar-grid`                                 | `''` | Present on the grid element. |

### RangeCalendar.GridBody

The body of the grid of dates in the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLTableSectionElement`                                                                                                                                                                            | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                          |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the grid element when the calendar is disabled.                    |
| `data-readonly`                                      | `''` | Present on the grid element when the calendar is readonly.                    |
| `data-calendar-grid-body`                            | `''` | Present on the grid body element. |

### RangeCalendar.GridHead

The head of the grid of dates in the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLTableSectionElement`                                                                                                                                                                            | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                          |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the grid head element when the calendar is disabled.               |
| `data-readonly`                                      | `''` | Present on the grid head element when the calendar is readonly.               |
| `data-calendar-grid-head`                            | `''` | Present on the grid head element. |

### RangeCalendar.GridRow

A row in the grid of dates in the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLTableRowElement`                                                                                                                                                                                | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                         |
| -------------------------------------------------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the grid row element when the calendar is disabled.               |
| `data-readonly`                                      | `''` | Present on the grid row element when the calendar is readonly.               |
| `data-calendar-grid-row`                             | `''` | Present on the grid row element. |

### RangeCalendar.HeadCell

A cell in the head of the grid of dates in the calendar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLTableCellElement`                                                                                                                                                                               | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                | Value         | Description                                                                                          |
| -------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present on the head cell element when the calendar is disabled.               |
| `data-readonly`                                      | `''` | Present on the head cell element when the calendar is readonly.               |
| `data-calendar-head-cell`                            | `''` | Present on the head cell element. |

----------------------------------------------------

# Scroll Area Documentation

Provides a consistent scroll area across platforms.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { ScrollArea } from "bits-ui";
</script>
<ScrollArea.Root
  class="border-dark-10 bg-background-alt shadow-card relative overflow-hidden rounded-[10px] border px-4 py-4"
>
  <ScrollArea.Viewport class="h-full max-h-[200px] w-full max-w-[200px]">
    <h4
      class="text-foreground mb-4 mt-2 text-xl font-semibold leading-none tracking-[-0.01em]"
    >
      Scroll Area
    </h4>
    <p class="text-foreground-alt text-wrap text-sm leading-5">
      Lorem ipsum dolor sit, amet consectetur adipisicing elit. Dignissimos
      impedit rem, repellat deserunt ducimus quasi nisi voluptatem cumque
      aliquid esse ea deleniti eveniet incidunt! Deserunt minus laborum
      accusamus iusto dolorum. Lorem ipsum dolor sit, amet consectetur
      adipisicing elit. Blanditiis officiis error minima eos fugit voluptate
      excepturi eveniet dolore et, ratione impedit consequuntur dolorem hic quae
      corrupti autem? Dolorem, sit voluptatum.
    </p>
  </ScrollArea.Viewport>
  <ScrollArea.Scrollbar
    orientation="vertical"
    class="bg-muted hover:bg-dark-10 data-[state=visible]:animate-in data-[state=hidden]:animate-out data-[state=hidden]:fade-out-0 data-[state=visible]:fade-in-0 flex w-2.5 touch-none select-none rounded-full border-l border-l-transparent p-px transition-all duration-200 hover:w-3"
  >
    <ScrollArea.Thumb class="bg-muted-foreground flex-1 rounded-full" />
  </ScrollArea.Scrollbar>
  <ScrollArea.Scrollbar
    orientation="horizontal"
    class="bg-muted hover:bg-dark-10 flex h-2.5 touch-none select-none rounded-full border-t border-t-transparent p-px transition-all duration-200 hover:h-3 "
  >
    <ScrollArea.Thumb class="bg-muted-foreground rounded-full" />
  </ScrollArea.Scrollbar>
  <ScrollArea.Corner />
</ScrollArea.Root>
```

## Structure

```svelte
<script lang="ts">
 import { ScrollArea } from "bits-ui";
</script>
<ScrollArea.Root>
 <ScrollArea.Viewport>
 </ScrollArea.Viewport>
 <ScrollArea.Scrollbar orientation="vertical">
  <ScrollArea.Thumb />
 </ScrollArea.Scrollbar>
 <ScrollArea.Scrollbar orientation="horizontal">
  <ScrollArea.Thumb />
 </ScrollArea.Scrollbar>
 <ScrollArea.Corner />
</ScrollArea.Root>
```

## Reusable Components

If you're planning to use the Scroll Area throughout your application, it's recommended to create a reusable component to reduce the amount of code you need to write each time.

This example shows you how to create a Scroll Area component that accepts a few custom props that make it more capable.

MyScrollArea.svelte

```svelte
<script lang="ts">
 import { ScrollArea, type WithoutChild } from "bits-ui";
 type Props = WithoutChild<ScrollArea.RootProps> & {
  orientation: "vertical" | "horizontal" | "both";
  viewportClasses?: string;
 };
 let {
  ref = $bindable(null),
  orientation = "vertical",
  viewportClasses,
  children,
  ...restProps
 }: Props = $props();
</script>
{#snippet Scrollbar({ orientation }: { orientation: "vertical" | "horizontal" })}
 <ScrollArea.Scrollbar {orientation}>
  <ScrollArea.Thumb />
 </ScrollArea.Scrollbar>
{/snippet}
<ScrollArea.Root bind:ref {...restProps}>
 <ScrollArea.Viewport class={viewportClasses}>
  {@render children?.()}
 </ScrollArea.Viewport>
 {#if orientation === "vertical" || orientation === "both"}
  {@render Scrollbar({ orientation: "vertical" })}
 {/if}
 {#if orientation === "horizontal" || orientation === "both"}
  {@render Scrollbar({ orientation: "horizontal" })}
 {/if}
 <ScrollArea.Corner />
</ScrollArea.Root>
```

We'll use this custom component in the following examples to demonstrate how to customize the behavior of the Scroll Area.

## Scroll Area Types

### Hover

The `hover` type is the default type of the scroll area, demonstrated in the featured example above. It only shows scrollbars when the user hovers over the scroll area and the content is larger than the viewport.

```svelte
<MyScrollArea type="hover">
</MyScrollArea>
```

### Scroll

The `scroll` type displays the scrollbars when the user scrolls the content. This is similar to the behavior of MacOS.

```svelte
<MyScrollArea type="scroll">
</MyScrollArea>
```

### Auto

The `auto` type behaves similarly to your typical browser scrollbars. When the content is larger than the viewport, the scrollbars will appear and remain visible at all times.

```svelte
<MyScrollArea type="auto">
</MyScrollArea>
```

### Always

The `always` type behaves as if you set `overflow: scroll` on the scroll area. Scrollbars will always be visible, even when the content is smaller than the viewport. We've also set the `orientation` prop on the `MyScrollArea` to `'both'` to ensure both scrollbars are rendered.

```svelte
<MyScrollArea type="always" orientation="both">
</MyScrollArea>
```

## Customizing the Hide Delay

You can customize the hide delay of the scrollbars using the `scrollHideDelay` prop.

```svelte
<MyScrollArea scrollHideDelay={10}>
</MyScrollArea>
```

## API Reference

### ScrollArea.Root

The container of all scroll area components. Overflow is hidden on this element to prevent double scrollbars.

| Property                                                              | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `enum`- 'hover' \| 'scroll' \| 'auto' \| 'always'                    | The type of scroll area.`Default: 'hover'`                                                                                                                                        |
| `scrollHideDelay`                   | `number`                                                                                                                                                                                             | The delay in milliseconds before the scroll area hides itself when using `'hover'` or `'scroll'` type.`Default: 600`                                                              |
| `dir`                               | `enum`- 'ltr' \| 'rtl'                                               | The reading direction of the app.`Default: 'ltr'`                                                                                                                                 |
| `ref` $bindable        | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                          | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                             | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                        | Value         | Description                                                                                     |
| ---------------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-scroll-area-root` | `''` | Present on the root element. |

### ScrollArea.Viewport

The component which wraps the content and is responsible for computing the scroll area size.

| Property                                                                                    | Type                                                        | Description                                                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined` |
| `children`                                                | `Snippet`        | The children content to render.`Default:  undefined`                                |

| Data Attribute                                            | Value         | Description                                                                                         |
| -------------------------------------------------------------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-scroll-area-viewport` | `''` | Present on the viewport element. |

### ScrollArea.Scrollbar

A scrollbar of the scroll area.

| Property                                                                                           | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `orientation` required | `enum`- 'horizontal' \| 'vertical'                                   | The orientation of the scrollbar.`Default:  undefined`                                                                                                                         |
| `forceMount`                                                     | `boolean`                                                                                                                                                                                            | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                |
| `ref` $bindable                                     | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                       | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                          | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value                                                                                                                                                                         | Description                                                                                                       |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- '' | The visibility state of the scrollbar                                                      |
| `data-scroll-area-scrollbar-x`                    | `''`                                                                                                                                                                 | Present on the `'horizontal'` scrollbar element.                                           |
| `data-scroll-area-scrollbar-y`                    | `''`                                                                                                                                                                 | Present on the `'vertical'` scrollbar element. |

### ScrollArea.Thumb

A thumb of a scrollbar in the scroll area.

| Property                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `forceMount` | `boolean`                                                                                                                                                                                            | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                |
| `ref` $bindable              | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value                                                                                                                                                                         | Description                                                                                                   |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- '' | The visibility state of the scrollbar                                                  |
| `data-scroll-area-thumb-x`                        | `''`                                                                                                                                                                 | Present on the `'horizontal'` thumb element.                                           |
| `data-scroll-area-thumb-y`                        | `''`                                                                                                                                                                 | Present on the `'vertical'` thumb element. |

### ScrollArea.Corner

The corner element between the X and Y scrollbars.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                          | Value         | Description                                                                                       |
| ------------------------------------------------------------------------------------------ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-scroll-area-corner` | `''` | Present on the corner element. |

----------------------------------------------------

# Select Documentation

Enables users to choose from a list of options presented in a dropdown.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { Select } from "bits-ui";
  import Check from "phosphor-svelte/lib/Check";
  import Palette from "phosphor-svelte/lib/Palette";
  import CaretUpDown from "phosphor-svelte/lib/CaretUpDown";
  import CaretDoubleUp from "phosphor-svelte/lib/CaretDoubleUp";
  import CaretDoubleDown from "phosphor-svelte/lib/CaretDoubleDown";
  const themes = [
    { value: "light-monochrome", label: "Light Monochrome" },
    { value: "dark-green", label: "Dark Green" },
    { value: "svelte-orange", label: "Svelte Orange" },
    { value: "punk-pink", label: "Punk Pink" },
    { value: "ocean-blue", label: "Ocean Blue", disabled: true },
    { value: "sunset-red", label: "Sunset Red" },
    { value: "forest-green", label: "Forest Green" },
    { value: "lavender-purple", label: "Lavender Purple", disabled: true },
    { value: "mustard-yellow", label: "Mustard Yellow" },
    { value: "slate-gray", label: "Slate Gray" },
    { value: "neon-green", label: "Neon Green" },
    { value: "coral-reef", label: "Coral Reef" },
    { value: "midnight-blue", label: "Midnight Blue" },
    { value: "crimson-red", label: "Crimson Red" },
    { value: "mint-green", label: "Mint Green" },
    { value: "pastel-pink", label: "Pastel Pink" },
    { value: "golden-yellow", label: "Golden Yellow" },
    { value: "deep-purple", label: "Deep Purple" },
    { value: "turquoise-blue", label: "Turquoise Blue" },
    { value: "burnt-orange", label: "Burnt Orange" }
  ];
  let value = $state<string>("");
  const selectedLabel = $derived(
    value
      ? themes.find((theme) => theme.value === value)?.label
      : "Select a theme"
  );
</script>
<Select.Root type="single" onValueChange={(v) => (value = v)}>
  <Select.Trigger
    class="h-input rounded-9px border-border-input bg-background data-placeholder:text-foreground-alt/50 inline-flex w-[296px] select-none items-center border px-[11px] text-sm transition-colors"
    aria-label="Select a theme"
  >
    <Palette class="text-muted-foreground mr-[9px] size-6" />
    {selectedLabel}
    <CaretUpDown class="text-muted-foreground ml-auto size-6" />
  </Select.Trigger>
  <Select.Portal>
    <Select.Content
      class="focus-override border-muted bg-background shadow-popover data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 outline-hidden z-50 h-96 max-h-[var(--bits-select-content-available-height)] w-[var(--bits-select-anchor-width)] min-w-[var(--bits-select-anchor-width)] select-none rounded-xl border px-1 py-3 data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1"
      sideOffset={10}
    >
      <Select.ScrollUpButton class="flex w-full items-center justify-center">
        <CaretDoubleUp class="size-3" />
      </Select.ScrollUpButton>
      <Select.Viewport class="p-1">
        {#each themes as theme, i (i + theme.value)}
          <Select.Item
            class="rounded-button data-highlighted:bg-muted outline-hidden data-disabled:opacity-50 flex h-10 w-full select-none items-center py-3 pl-5 pr-1.5 text-sm  capitalize"
            value={theme.value}
            label={theme.label}
            disabled={theme.disabled}
          >
            {#snippet children({ selected })}
              {theme.label}
              {#if selected}
                <div class="ml-auto">
                  <Check />
                </div>
              {/if}
            {/snippet}
          </Select.Item>
        {/each}
      </Select.Viewport>
      <Select.ScrollDownButton class="flex w-full items-center justify-center">
        <CaretDoubleDown class="size-3" />
      </Select.ScrollDownButton>
    </Select.Content>
  </Select.Portal>
</Select.Root>
```

## Overview

The Select component provides users with a selectable list of options. It's designed to offer an enhanced selection experience with features like typeahead search, keyboard navigation, and customizable grouping. This component is particularly useful for scenarios where users need to choose from a predefined set of options, offering more functionality than a standard select element.

## Key Features

- **Typeahead Search**: Users can quickly find options by typing  
- **Keyboard Navigation**: Full support for keyboard interactions, allowing users to navigate through options using arrow keys, enter to select, and more.  
- **Grouped Options**: Ability to organize options into logical groups, enhancing readability and organization of large option sets.  
- **Scroll Management**: Includes scroll up/down buttons for easy navigation in long lists.  
- **Accessibility**: Built-in ARIA attributes and keyboard support ensure compatibility with screen readers and adherence to accessibility standards.  
- **Portal Support**: Option to render the select content in a portal, preventing layout issues in complex UI structures. ## Architecture

The Select component is composed of several sub-components, each with a specific role:

- **Root**: The main container component that manages the state and context for the combobox.  
- **Trigger**: The button or element that opens the dropdown list.  
- **Portal**: Responsible for portalling the dropdown content to the body or a custom target.  
- **Group**: A container for grouped items, used to group related items.  
- **GroupHeading**: A heading for a group of items, providing a descriptive label for the group.  
- **Item**: An individual item within the list.  
- **Separator**: A visual separator between items.  
- **Content**: The dropdown container that displays the items. It uses [Floating UI](https://floating-ui.com/)
  to position the content relative to the trigger.
- **ContentStatic** (Optional): An alternative to the Content component, that enables you to opt-out of Floating UI and position the content yourself.  
- **Arrow**: An arrow element that points to the trigger when using the `Combobox.Content` component.

## Structure

Here's an overview of how the Select component is structured in code:

```svelte
<script lang="ts">
 import { Select } from "bits-ui";
</script>
<Select.Root>
 <Select.Trigger />
 <Select.Portal>
  <Select.Content>
   <Select.ScrollUpButton />
   <Select.Viewport>
    <Select.Item />
    <Select.Group>
     <Select.GroupHeading />
     <Select.Item />
    </Select.Group>
    <Select.ScrollDownButton />
   </Select.Viewport>
  </Select.Content>
 </Select.Portal>
</Select.Root>
```

## Reusable Components

As you can see from the structure above, there are a number of pieces that make up the `Select` component. These pieces are provided to give you maximum flexibility and customization options, but can be a burden to write out everywhere you need to use a select in your application.

To ease this burden, it's recommended to create your own reusable select component that wraps the primitives and provides a more convenient API for your use cases.

Here's an example of how you might create a reusable `MySelect` component that receives a list of options and renders each of them as an item.

MySelect.svelte

```svelte
<script lang="ts">
 import { Select, type WithoutChildren } from "bits-ui";
 type Props = WithoutChildren<Select.RootProps> & {
  placeholder?: string;
  items: { value: string; label: string; disabled?: boolean }[];
  contentProps?: WithoutChildren<Select.ContentProps>;
  // any other specific component props if needed
 };
 let { value = $bindable(), items, contentProps, placeholder, ...restProps }: Props = $props();
 const selectedLabel = $derived(items.find((item) => item.value === value)?.label);
</script>

<Select.Root bind:value={value as never} {...restProps}>
 <Select.Trigger>
  {selectedLabel ? selectedLabel : placeholder}
 </Select.Trigger>
 <Select.Portal>
  <Select.Content {...contentProps}>
   <Select.ScrollUpButton>up</Select.ScrollUpButton>
   <Select.Viewport>
    {#each items as { value, label, disabled } (value)}
     <Select.Item {value} {label} {disabled}>
      {#snippet children({ selected })}
       {selected ? "" : ""}
       {item.label}
      {/snippet}
     </Select.Item>
    {/each}
   </Select.Viewport>
   <Select.ScrollDownButton>down</Select.ScrollDownButton>
  </Select.Content>
 </Select.Portal>
</Select.Root>
```

You can then use the `MySelect` component throughout your application like so:

```svelte
<script lang="ts">
 import MySelect from "$lib/components/MySelect.svelte";
 const items = [
  { value: "apple", label: "Apple" },
  { value: "banana", label: "Banana" },
  { value: "cherry", label: "Cherry" },
 ];
 let fruit = $state("apple");
</script>
<MySelect {items} bind:value={fruit} />
```

## Managing Value State

This section covers how to manage the `value` state of the component.

### Two-Way Binding

Use `bind:value` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { Select } from "bits-ui";
 let myValue = $state("");
</script>
<button onclick={() => (myValue = "A")}> Select A </button>
<Select.Root type="single" bind:value={myValue}>
</Select.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { Select } from "bits-ui";
 let myValue = $state("");
 function getValue() {
  return myValue;
 }
 function setValue(newValue: string) {
  myValue = newValue;
 }
</script>
<Select.Root type="single" bind:value={getValue, setValue}>
</Select.Root>
```

## Managing Open State

This section covers how to manage the `open` state of the component.

### Two-Way Binding

Use `bind:open` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { Select } from "bits-ui";
 let myOpen = $state(false);
</script>
<button onclick={() => (myOpen = true)}> Open </button>
<Select.Root bind:open={myOpen}>
</Select.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { Select } from "bits-ui";
 let myOpen = $state(false);
 function getOpen() {
  return myOpen;
 }
 function setOpen(newOpen: boolean) {
  myOpen = newOpen;
 }
</script>
<Select.Root bind:open={getOpen, setOpen}>
</Select.Root>
```

## Multiple Selection

The `type` prop can be set to `'multiple'` to allow multiple items to be selected at a time.

```svelte
<script lang="ts">
 import { Select } from "bits-ui";
 let value = $state<string[]>([]);
</script>
<Select.Root type="multiple" bind:value>
</Select.Root>
```

```svelte
<script lang="ts">
  import { Select } from "bits-ui";
  import CaretDoubleDown from "phosphor-svelte/lib/CaretDoubleDown";
  import CaretDoubleUp from "phosphor-svelte/lib/CaretDoubleUp";
  import CaretUpDown from "phosphor-svelte/lib/CaretUpDown";
  import Check from "phosphor-svelte/lib/Check";
  import Palette from "phosphor-svelte/lib/Palette";
  const themes = [
    { value: "light-monochrome", label: "Light Monochrome" },
    { value: "dark-green", label: "Dark Green" },
    { value: "svelte-orange", label: "Svelte Orange" },
    { value: "punk-pink", label: "Punk Pink" },
    { value: "ocean-blue", label: "Ocean Blue" },
    { value: "sunset-red", label: "Sunset Red" },
    { value: "forest-green", label: "Forest Green" },
    { value: "lavender-purple", label: "Lavender Purple" },
    { value: "mustard-yellow", label: "Mustard Yellow" },
    { value: "slate-gray", label: "Slate Gray" },
    { value: "neon-green", label: "Neon Green" },
    { value: "coral-reef", label: "Coral Reef" },
    { value: "midnight-blue", label: "Midnight Blue" },
    { value: "crimson-red", label: "Crimson Red" },
    { value: "mint-green", label: "Mint Green" },
    { value: "pastel-pink", label: "Pastel Pink" },
    { value: "golden-yellow", label: "Golden Yellow" },
    { value: "deep-purple", label: "Deep Purple" },
    { value: "turquoise-blue", label: "Turquoise Blue" },
    { value: "burnt-orange", label: "Burnt Orange" }
  ];
  let value = $state<string[]>([]);
  const selectedLabel = $derived(
    value.length
      ? themes
          .filter((theme) => value.includes(theme.value))
          .map((theme) => theme.label)
          .join(", ")
      : "Select your favorite themes"
  );
</script>
<Select.Root type="multiple" bind:value>
  <Select.Trigger
    class="h-input rounded-9px border-border-input bg-background data-placeholder:text-foreground-alt/50 inline-flex w-[296px] select-none items-center border px-[11px] text-sm transition-colors"
    aria-label="Select a theme"
  >
    <Palette class="text-muted-foreground mr-[9px] size-6" />
    <span class="w-[calc(296px-11px-11px-9px)] truncate text-start">
      {selectedLabel}
    </span>
    <CaretUpDown class="text-muted-foreground ml-auto size-6" />
  </Select.Trigger>
  <Select.Portal>
    <Select.Content
      class="focus-override border-muted bg-background shadow-popover data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 outline-hidden z-50 h-96 max-h-[var(--bits-select-content-available-height)] w-[var(--bits-select-anchor-width)] min-w-[var(--bits-select-anchor-width)] select-none rounded-xl border px-1 py-3 data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1"
      sideOffset={10}
    >
      <Select.ScrollUpButton class="flex w-full items-center justify-center">
        <CaretDoubleUp class="size-3" />
      </Select.ScrollUpButton>
      <Select.Viewport class="p-1">
        {#each themes as theme, i (i + theme.value)}
          <Select.Item
            class="rounded-button data-highlighted:bg-muted outline-hidden flex h-10 w-full select-none items-center py-3 pl-5 pr-1.5 text-sm capitalize"
            value={theme.value}
            label={theme.label}
          >
            {#snippet children({ selected })}
              {theme.label}
              {#if selected}
                <div class="ml-auto">
                  <Check />
                </div>
              {/if}
            {/snippet}
          </Select.Item>
        {/each}
      </Select.Viewport>
      <Select.ScrollDownButton class="flex w-full items-center justify-center">
        <CaretDoubleDown class="size-3" />
      </Select.ScrollDownButton>
    </Select.Content>
  </Select.Portal>
</Select.Root>
```

## Opt-out of Floating UI

When you use the `Select.Content` component, Bits UI uses [Floating UI](https://floating-ui.com/) to position the content relative to the trigger, similar to other popover-like components.

You can opt-out of this behavior by instead using the `Select.ContentStatic` component.

```svelte
<Select.Root>
 <Select.Trigger />
 <Select.Portal>
  <Select.ContentStatic>
   <Select.ScrollUpButton />
   <Select.Viewport>
    <Select.Item />
    <Select.Group>
     <Select.GroupHeading />
     <Select.Item />
    </Select.Group>
    <Select.ScrollDownButton />
   </Select.Viewport>
  </Select.ContentStatic>
 </Select.Portal>
</Select.Root>
```

When using this component, you'll need to handle the positioning of the content yourself. Keep in mind that using `Select.Portal` alongside `Select.ContentStatic` may result in some unexpected positioning behavior, feel free to not use the portal or work around it.

## Custom Anchor

By default, the `Select.Content` is anchored to the `Select.Trigger` component, which determines where the content is positioned.

If you wish to instead anchor the content to a different element, you can pass either a selector string or an `HTMLElement` to the `customAnchor` prop of the `Select.Content` component.

```svelte
<script lang="ts">
 import { Select } from "bits-ui";
 let customAnchor = $state<HTMLElement>(null!);
</script>
<div bind:this={customAnchor}></div>
<Select.Root>
 <Select.Trigger />
 <Select.Content {customAnchor}>
 </Select.Content>
</Select.Root>
```

## What is the Viewport?

The `Select.Viewport` component is used to determine the size of the content in order to determine whether or not the scroll up and down buttons should be rendered.

If you wish to set a minimum/maximum height for the select content, you should apply it to the `Select.Viewport` component.

## Scroll Up/Down Buttons

The `Select.ScrollUpButton` and `Select.ScrollDownButton` components are used to render the scroll up and down buttons when the select content is larger than the viewport.

You must use the `Select.Viewport` component when using the scroll buttons.

## Native Scrolling/Overflow

If you don't want to use the scroll buttons and prefer to use the standard scrollbar/overflow behavior, you can omit the `Select.Scroll[Up|Down]Button` components and the `Select.Viewport` component.

You'll need to set a height on the `Select.Content` component and appropriate `overflow` styles to enable scrolling.

## Scroll Lock

By default, when a user opens the select, scrolling outside the content will not be disabled. You can override this behavior by setting the `preventScroll` prop to `true`.

```svelte
<Select.Content preventScroll={true}>
</Select.Content>
```

## Highlighted Items

The Select component follows the [WAI-ARIA descendant pattern](https://www.w3.org/TR/wai-aria-practices-1.2/#combobox) for highlighting items. This means that the `Select.Trigger` retains focus the entire time, even when navigating with the keyboard, and items are highlighted as the user navigates them.

### Styling Highlighted Items

You can use the `data-highlighted` attribute on the `Select.Item` component to style the item differently when it is highlighted.

### onHighlight / onUnhighlight

To trigger side effects when an item is highlighted or unhighlighted, you can use the `onHighlight` and `onUnhighlight` props.

```svelte
<Select.Item onHighlight={() => console.log('I am highlighted!')} onUnhighlight={() => console.log('I am unhighlighted!')} />

</Select.Item>
```

## Svelte Transitions

You can use the `forceMount` prop along with the `child` snippet to forcefully mount the `Select.Content` component to use Svelte Transitions or another animation library that requires more control.

```svelte
<script lang="ts">
 import { Select } from "bits-ui";
 import { fly } from "svelte/transition";
</script>
<Select.Content forceMount>
 {#snippet child({ wrapperProps, props, open })}
  {#if open}
   <div {...wrapperProps}>
    <div {...props} transition:fly>
    </div>
   </div>
  {/if}
 {/snippet}
</Select.Content>
```

Of course, this isn't the prettiest syntax, so it's recommended to create your own reusable content component that handles this logic if you intend to use this approach. For more information on using transitions with Bits UI components, see the [Transitions](/docs/transitions) documentation.

```svelte
<script lang="ts">
  import { Select } from "bits-ui";
  import Check from "phosphor-svelte/lib/Check";
  import Palette from "phosphor-svelte/lib/Palette";
  import CaretUpDown from "phosphor-svelte/lib/CaretUpDown";
  import CaretDoubleUp from "phosphor-svelte/lib/CaretDoubleUp";
  import CaretDoubleDown from "phosphor-svelte/lib/CaretDoubleDown";
  import { fly } from "svelte/transition";
  const themes = [
    { value: "light-monochrome", label: "Light Monochrome" },
    { value: "dark-green", label: "Dark Green" },
    { value: "svelte-orange", label: "Svelte Orange" },
    { value: "punk-pink", label: "Punk Pink" },
    { value: "ocean-blue", label: "Ocean Blue" },
    { value: "sunset-red", label: "Sunset Red" },
    { value: "forest-green", label: "Forest Green" },
    { value: "lavender-purple", label: "Lavender Purple" },
    { value: "mustard-yellow", label: "Mustard Yellow" },
    { value: "slate-gray", label: "Slate Gray" },
    { value: "neon-green", label: "Neon Green" },
    { value: "coral-reef", label: "Coral Reef" },
    { value: "midnight-blue", label: "Midnight Blue" },
    { value: "crimson-red", label: "Crimson Red" },
    { value: "mint-green", label: "Mint Green" },
    { value: "pastel-pink", label: "Pastel Pink" },
    { value: "golden-yellow", label: "Golden Yellow" },
    { value: "deep-purple", label: "Deep Purple" },
    { value: "turquoise-blue", label: "Turquoise Blue" },
    { value: "burnt-orange", label: "Burnt Orange" }
  ];
  let value = $state<string>("");
  const selectedLabel = $derived(
    value
      ? themes.find((theme) => theme.value === value)?.label
      : "Select a theme"
  );
</script>
<Select.Root type="single" bind:value items={themes}>
  <Select.Trigger
    class="h-input rounded-9px border-border-input bg-background placeholder:text-foreground-alt/50 inline-flex w-[296px] select-none items-center border px-[11px] text-sm transition-colors"
    aria-label="Select a theme"
  >
    <Palette class="text-muted-foreground mr-[9px] size-6" />
    {selectedLabel}
    <CaretUpDown class="text-muted-foreground ml-auto size-6" />
  </Select.Trigger>
  <Select.Portal>
    <Select.Content
      class="focus-override border-muted bg-background shadow-popover outline-hidden z-50 h-96 max-h-[var(--bits-select-content-available-height)] w-[var(--bits-select-anchor-width)] min-w-[var(--bits-select-anchor-width)] select-none rounded-xl border px-1 py-3"
      sideOffset={10}
      forceMount
    >
      {#snippet child({ wrapperProps, props, open })}
        {#if open}
          <div {...wrapperProps}>
            <div {...props} transition:fly={{ duration: 300 }}>
              <Select.ScrollUpButton
                class="flex w-full items-center justify-center"
              >
                <CaretDoubleUp class="size-3" />
              </Select.ScrollUpButton>
              <Select.Viewport class="p-1">
                {#each themes as theme, i (i + theme.value)}
                  <Select.Item
                    class="rounded-button data-highlighted:bg-muted outline-hidden flex h-10 w-full select-none items-center py-3 pl-5 pr-1.5 text-sm capitalize duration-75"
                    value={theme.value}
                    label={theme.label}
                  >
                    {#snippet children({ selected })}
                      {theme.label}
                      {#if selected}
                        <div class="ml-auto">
                          <Check />
                        </div>
                      {/if}
                    {/snippet}
                  </Select.Item>
                {/each}
              </Select.Viewport>
              <Select.ScrollDownButton
                class="flex w-full items-center justify-center"
              >
                <CaretDoubleDown class="size-3" />
              </Select.ScrollDownButton>
            </div>
          </div>
        {/if}
      {/snippet}
    </Select.Content>
  </Select.Portal>
</Select.Root>
```

## API Reference

### Select.Root

The root select component which manages & scopes the state of the select.

| Property                                                                                    | Type                                                                                                                                                                                                                                         | Description                                                                                                                                                                                                                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type` required | `enum`- 'single' \| 'multiple'                                    | The type of selection to use for the select.`Default:  undefined`                                                                                                                                                                                                                       |
| `value` $bindable                            | `union`- string \| string\[]                                      | The value of the select. When the type is `'single'`, this should be a string. When the type is `'multiple'`, this should be an array of strings.`Default:  undefined`                                                                                                                  |
| `onValueChange`                                           | `function`- (value: string) => void \| (value: string\[]) => void | A callback that is fired when the select value changes. When the type is `'single'`, the argument will be a string. When the type is `'multiple'`, the argument will be an array of strings.`Default:  undefined`                                                                       |
| `open` $bindable                             | `boolean`                                                                                                                                                                                         | The open state of the select menu.`Default: false`                                                                                                                                                                                                                                         |
| `onOpenChange`                                            | `function`- (open: boolean) => void                               | A callback that is fired when the select menu's open state changes.`Default:  undefined`                                                                                                                                                                                                |
| `disabled`                                                | `boolean`                                                                                                                                                                                         | Whether or not the select component is disabled.`Default: false`                                                                                                                                                                                                                           |
| `name`                                                    | `string`                                                                                                                                                                                          | The name to apply to the hidden input element for form submission. If provided, a hidden input element will be rendered to submit the value of the select.`Default:  undefined`                                                                                                         |
| `required`                                                | `boolean`                                                                                                                                                                                         | Whether or not the select menu is required.`Default: false`                                                                                                                                                                                                                                |
| `scrollAlignment`                                         | `enum`- 'nearest' \| 'center'                                     | The alignment of the highlighted item when scrolling.`Default: 'nearest'`                                                                                                                                                                                                                  |
| `loop`                                                    | `boolean`                                                                                                                                                                                         | Whether or not the select menu should loop through items.`Default: false`                                                                                                                                                                                                                  |
| `allowDeselect`                                           | `boolean`                                                                                                                                                                                         | Whether or not the user can deselect the selected item by pressing it in a single select.`Default: false`                                                                                                                                                                                  |
| `items`                                                   | `object`- { value: string; label: string; disabled?: boolean}\[]  | Optionally provide an array of `value` and `label` pairs that will be used to match and trigger selection when the trigger is focused and a key is pressed while the content is closed. Additionally, this will be used for form autofill when the type is single.`Default:  undefined` |
| `children`                                                | `Snippet`                                                                                                                                                                                         | The children content to render.`Default:  undefined`                                                                                                                                                                                                |

### Select.Trigger

A button which toggles the select's open state.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                        |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | The select's open state.                                                    |
| `data-placeholder`                                | `''`                                                                                                                                                                                 | Present when the select does not have a value.                              |
| `data-disabled`                                   | `''`                                                                                                                                                                                 | Present when the select is disabled.                                        |
| `data-select-trigger`                             | `''`                                                                                                                                                                                 | Present on the trigger element. |

### Select.Content

The element which contains the select's items.

| Property                                                              | Type                                                                                                                                                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `side` | `enum`- 'top' \| 'bottom' \| 'left' \| 'right'                                     | The preferred side of the anchor to render the floating element against when open. Will be reversed when collisions occur.`Default: bottom`                                                                                                                                                                                                                                                                                        |
| `sideOffset`                        | `number`                                                                                                                                                                                                           | The distance in pixels from the anchor to the floating element.`Default: 0`                                                                                                                                                                                                                                                                                                                                                        |
| `align`                             | `enum`- 'start' \| 'center' \| 'end'                                               | The preferred alignment of the anchor to render the floating element against when open. This may change when collisions occur.`Default: start`                                                                                                                                                                                                                                                                                     |
| `alignOffset`                       | `number`                                                                                                                                                                                                           | The distance in pixels from the anchor to the floating element.`Default: 0`                                                                                                                                                                                                                                                                                                                                                        |
| `arrowPadding`                      | `number`                                                                                                                                                                                                           | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0`                                                                                                                                                                                                                                                                                                  |
| `avoidCollisions`                   | `boolean`                                                                                                                                                                                                          | When `true`, overrides the `side` and `align` options to prevent collisions with the boundary edges.`Default: true`                                                                                                                                                                                                                                                                                                                |
| `collisionBoundary`                 | `union`- Element \| null                                                           | A boundary element or array of elements to check for collisions against.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                   |
| `collisionPadding`                  | `union`- number \| Partial\&lt;Record\&lt;Side, number\&gt;\&gt;                   | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0`                                                                                                                                                                                                                                                                                                  |
| `sticky`                            | `enum`- 'partial' \| 'always'                                                      | The sticky behavior on the align axis. `'partial'` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst `'always'` will keep the content in the boundary regardless.`Default: partial`                                                                                                                                                                                        |
| `hideWhenDetached`                  | `boolean`                                                                                                                                                                                                          | When `true`, hides the content when it is detached from the DOM. This is useful for when you want to hide the content when the user scrolls away.`Default: true`                                                                                                                                                                                                                                                                   |
| `updatePositionStrategy`            | `enum`- 'optimized' \| 'always'                                                    | The strategy to use when updating the position of the content. When `'optimized'` the content will only be repositioned when the trigger is in the viewport. When `'always'` the content will be repositioned whenever the position changes.`Default: optimized`                                                                                                                                                                   |
| `strategy`                          | `enum`- 'fixed' \| 'absolute'                                                      | The positioning strategy to use for the floating element. When `'fixed'` the element will be positioned relative to the viewport. When `'absolute'` the element will be positioned relative to the nearest positioned ancestor.`Default: fixed`                                                                                                                                                                                    |
| `preventScroll`                     | `boolean`                                                                                                                                                                                                          | When `true`, prevents the body from scrolling when the content is open. This is useful when you want to use the content as a modal.`Default: false`                                                                                                                                                                                                                                                                                |
| `customAnchor`                      | `union`- string \| HTMLElement \| Measurable \| null                               | Use an element other than the trigger to anchor the content to. If provided, the content will be anchored to the provided element instead of the trigger.`Default: null`                                                                                                                                                                                                                                                           |
| `onEscapeKeydown`                   | `function`- (event: KeyboardEvent) => void                                         | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default:  undefined`                                                                                                                                                                                                                    |
| `escapeKeydownBehavior`             | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` |
| `onInteractOutside`                 | `function`- (event: PointerEvent) => void                                          | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default:  undefined`                                                                                                                                                                                                        |
| `onFocusOutside`                    | `function`- (event: FocusEvent) => void                                            | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default:  undefined`                                                                                                                                                                                                                                                  |
| `interactOutsideBehavior`           | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close`  |
| `preventOverflowTextSelection`      | `boolean`                                                                                                                                                                                                          | When `true`, prevents the text selection from overflowing the bounds of the element.`Default: true`                                                                                                                                                                                                                                                                                                                                |
| `dir`                               | `enum`- 'ltr' \| 'rtl'                                                             | The reading direction of the app.`Default: 'ltr'`                                                                                                                                                                                                                                                                                                                                                                                  |
| `loop`                              | `boolean`                                                                                                                                                                                                          | Whether or not the select should loop through items when reaching the end.`Default: false`                                                                                                                                                                                                                                                                                                                                         |
| `forceMount`                        | `boolean`                                                                                                                                                                                                          | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                                                                                                                                                                                                                                                                 |
| `ref` $bindable        | `HTMLDivElement`                                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                                                                                                                                                                         |
| `children`                          | `Snippet`- Snippet                                                                 | The children content to render.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                                                            |
| `child`                             | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };               | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                                                                                                                                                                  | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                        |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | The select's open state.                                                    |
| `data-select-content`                             | `''`                                                                                                                                                                                 | Present on the content element. |

| CSS Variable                                                           | Description                                                                                                  |
| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--bits-select-content-transform-origin` | The transform origin of the select content element.                                   |
| `--bits-select-content-available-width`                                       | The available width of the select content element.                                    |
| `--bits-select-content-available-height`                                      | The available height of the select content element.                                   |
| `--bits-select-anchor-width`                                                  | The width of the select trigger element.                                              |
| `--bits-select-anchor-height`                                                 | The height of the select trigger element. |

### Select.ContentStatic

The element which contains the select's items. (Static/No Floating UI)

| Property                                                                         | Type                                                                                                                                                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onEscapeKeydown` | `function`- (event: KeyboardEvent) => void                                         | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default:  undefined`                                                                                                                                                                                                                    |
| `escapeKeydownBehavior`                        | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` |
| `onInteractOutside`                            | `function`- (event: PointerEvent) => void                                          | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default:  undefined`                                                                                                                                                                                                        |
| `onFocusOutside`                               | `function`- (event: FocusEvent) => void                                            | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default:  undefined`                                                                                                                                                                                                                                                  |
| `interactOutsideBehavior`                      | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close`  |
| `onOpenAutoFocus`                              | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is opened. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `onCloseAutoFocus`                             | `function`- (event: Event) => void                                                 | Event handler called when auto-focusing the content as it is closed. Can be prevented.`Default:  undefined`                                                                                                                                                                                                                                                                                                                     |
| `trapFocus`                                    | `boolean`                                                                                                                                                                                                          | Whether or not to trap the focus within the content when open.`Default: true`                                                                                                                                                                                                                                                                                                                                                      |
| `preventScroll`                                | `boolean`                                                                                                                                                                                                          | When `true`, prevents the body from scrolling when the content is open. This is useful when you want to use the content as a modal.`Default: true`                                                                                                                                                                                                                                                                                 |
| `preventOverflowTextSelection`                 | `boolean`                                                                                                                                                                                                          | When `true`, prevents the text selection from overflowing the bounds of the element.`Default: true`                                                                                                                                                                                                                                                                                                                                |
| `dir`                                          | `enum`- 'ltr' \| 'rtl'                                                             | The reading direction of the app.`Default: 'ltr'`                                                                                                                                                                                                                                                                                                                                                                                  |
| `loop`                                         | `boolean`                                                                                                                                                                                                          | Whether or not the select should loop through items when reaching the end.`Default: false`                                                                                                                                                                                                                                                                                                                                         |
| `forceMount`                                   | `boolean`                                                                                                                                                                                                          | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                                                                                                                                                                                                                                                                 |
| `ref` $bindable                   | `HTMLDivElement`                                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                                                                                                                                                                         |
| `children`                                     | `Snippet`- Snippet                                                                 | The children content to render.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                                                            |
| `child`                                        | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };               | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                                                                                                                                                                  | | Data Attribute                             | Value                                                                                                                                                                                         | Description                                                                                        |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | The select's open state.                                                    |
| `data-select-content`                             | `''`                                                                                                                                                                                 | Present on the content element. |

### Select.Item

A select item, which must be a child of the `select.Content` component.

| Property                                                                                     | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` required | `string`                                                                                                                                                                                             | The value of the item.`Default:  undefined`                                                                                                                                    |
| `label`                                                    | `string`                                                                                                                                                                                             | The label of the item, which is what the list will be filtered by using typeahead behavior.`Default:  undefined`                                                               |
| `disabled`                                                 | `boolean`                                                                                                                                                                                            | Whether or not the select item is disabled. This will prevent interaction/selection.`Default: false`                                                                              |
| `onHighlight`                                              | `function`- () => void                                               | A callback that is fired when the item is highlighted.`Default:  undefined`                                                                                                    |
| `onUnhighlight`                                            | `function`- () => void                                               | A callback that is fired when the item is unhighlighted.`Default:  undefined`                                                                                                  |
| `ref` $bindable                               | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                 | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                    | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value             | Description                                                                                                                |
| ----------------------------------------------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-value` | `string` | The value of the select item.                                                                       |
| `data-label`                                      | `string` | The label of the select item.                                                                       |
| `data-disabled`                                   | `''`     | Present when the item is disabled.                                                                  |
| `data-highlighted`                                | `''`     | Present when the item is highlighted, which is either via keyboard navigation of the menu or hover. |
| `data-selected`                                   | `''`     | Present when the item is selected.                                                                  |
| `data-select-item`                                | `''`     | Present on the item element.                            |

### Select.Viewport

An optional element to track the scroll position of the select for rendering the scroll up/down buttons.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                       | Value         | Description                                                                                         |
| --------------------------------------------------------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-select-viewport` | `''` | Present on the viewport element. |

### Select.ScrollUpButton

An optional scroll up button element to improve the scroll experience within the select. Should be used in conjunction with the `select.Viewport` component.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                               | Value         | Description                                                                                                 |
| ----------------------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-select-scroll-up-button` | `''` | Present on the scroll up button element. |

### Select.ScrollDownButton

An optional scroll down button element to improve the scroll experience within the select. Should be used in conjunction with the `select.Viewport` component.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                                 | Value         | Description                                                                                                   |
| ------------------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-select-scroll-down-button` | `''` | Present on the scroll down button element. |

### Select.Group

A group of related select items.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                    | Value         | Description                                                                                      |
| ------------------------------------------------------------------------------------ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-select-group` | `''` | Present on the group element. |

### Select.GroupHeading

A heading for the parent select group. This is used to describe a group of related select items.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                            | Value         | Description                                                                                              |
| -------------------------------------------------------------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-select-group-heading` | `''` | Present on the group heading element. |

### Select.Arrow

An optional arrow element which points to the content when open.

| Property                                                               | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `width` | `number`                                                                                                                                                                                             | The width of the arrow in pixels.`Default: 8`                                                                                                                                     |
| `height`                             | `number`                                                                                                                                                                                             | The height of the arrow in pixels.`Default: 8`                                                                                                                                    |
| `ref` $bindable         | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                           | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                              | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value         | Description                                                                                      |
| ----------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-arrow` | `''` | Present on the arrow element. |

----------------------------------------------------

# Separator Documentation

Visually separates content or UI elements for clarity and organization.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { Separator } from "bits-ui";
</script>
<div>
  <div class="space-y-1">
    <h4 class="font-semibold">Bits UI</h4>
    <p class="text-muted-foreground text-sm">
      Headless UI components for Svelte.
    </p>
  </div>
  <Separator.Root
    class="bg-border my-4 shrink-0 data-[orientation=horizontal]:h-px data-[orientation=vertical]:h-full data-[orientation=horizontal]:w-full data-[orientation=vertical]:w-[1px]"
  />
  <div class="flex h-5 items-center space-x-4 text-sm">
    <div>Blog</div>
    <Separator.Root
      orientation="vertical"
      class="bg-border my-4 shrink-0 data-[orientation=horizontal]:h-px data-[orientation=vertical]:h-full data-[orientation=horizontal]:w-full data-[orientation=vertical]:w-[1px]"
    />
    <div>Docs</div>
    <Separator.Root
      orientation="vertical"
      class="bg-border my-4 shrink-0 data-[orientation=horizontal]:h-px data-[orientation=vertical]:h-full data-[orientation=horizontal]:w-full data-[orientation=vertical]:w-[1px]"
    />
    <div>Source</div>
  </div>
</div>
```

## Structure

```svelte
<script lang="ts">
 import { Separator } from "bits-ui";
</script>
<Separator.Root />
```

## API Reference

### Separator.Root

An element used to separate content.

| Property                                                                     | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `orientation` | `enum`- 'horizontal' \| 'vertical'                                   | The orientation of the separator.`Default: 'horizontal'`                                                                                                                          |
| `decorative`                               | `boolean`                                                                                                                                                                                            | Whether the separator is decorative or not, which will determine if it is announced by screen readers.`Default: false`                                                            |
| `ref` $bindable               | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                 | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                    | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                   | Value                                                                                                                                                                                                 | Description                                                                                     |
| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-orientation` | `enum`- 'horizontal' \| 'vertical' | The orientation of the separator.                                        |
| `data-separator-root`                                   | `''`                                                                                                                                                                                         | Present on the root element. |

----------------------------------------------------

# Slider Documentation

Allows users to select a value from a continuous range by sliding a handle.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { Slider } from "bits-ui";
  import { cn } from "$lib/utils/styles.js";
  let value = $state(50);
</script>
<div class="w-full md:max-w-[280px]">
  <Slider.Root
    type="single"
    bind:value
    class="relative flex w-full touch-none select-none items-center"
  >
    {#snippet children()}
      <span
        class="bg-dark-10 relative h-2 w-full grow cursor-pointer overflow-hidden rounded-full"
      >
        <Slider.Range class="bg-foreground absolute h-full" />
      </span>
      <Slider.Thumb
        index={0}
        class={cn(
          "border-border-input bg-background hover:border-dark-40 focus-visible:ring-foreground dark:bg-foreground dark:shadow-card focus-visible:outline-hidden block size-[25px] cursor-pointer rounded-full border shadow-sm transition-colors focus-visible:ring-2 focus-visible:ring-offset-2 active:scale-[0.98] disabled:pointer-events-none disabled:opacity-50"
        )}
      />
    {/snippet}
  </Slider.Root>
</div>
```

## Structure

```svelte
<script lang="ts">
 import { Slider } from "bits-ui";
</script>
<Slider.Root>
 <Slider.Range />
 <Slider.Thumb />
 <Slider.Tick />
</Slider.Root>
```

## Reusable Components

Bits UI provides primitives that enable you to build your own custom slider component that can be reused throughout your application.

Here's an example of how you might create a reusable `MySlider` component.

MyMultiSlider.svelte

```svelte
<script lang="ts">
 import type { ComponentProps } from "svelte";
 import { Slider } from "bits-ui";
 type Props = WithoutChildren<ComponentProps<typeof Slider.Root>>;
 let { value = $bindable(), ref = $bindable(null), ...restProps }: Props = $props();
</script>

<Slider.Root bind:value bind:ref {...restProps as any}>
 {#snippet children({ thumbs, ticks })}
  <Slider.Range />
  {#each thumbs as index}
   <Slider.Thumb {index} />
  {/each}
  {#each ticks as index}
   <Slider.Tick {index} />
  {/each}
 {/snippet}
</Slider.Root>
```

You can then use the `MySlider` component in your application like so:

```svelte
<script lang="ts">
 import MySlider from "$lib/components/MySlider.svelte";
 let multiValue = $state([5, 10]);
 let singleValue = $state(50);
</script>
<MySlider bind:value={multiValue} type="multiple" />
<MySlider bind:value={singleValue} type="single" />
```

## Managing Value State

This section covers how to manage the `value` state of the component.

### Two-Way Binding

Use `bind:value` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { Slider } from "bits-ui";
 let myValue = $state(0);
</script>
<button onclick={() => (myValue = 20)}> Set value to 20 </button>
<Slider.Root bind:value={myValue} type="single">
</Slider.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { Slider } from "bits-ui";
 let myValue = $state(0);
 function getValue() {
  return myValue;
 }
 function setValue(newValue: number) {
  myValue = newValue;
 }
</script>
<Slider.Root type="single" bind:value={getValue, setValue}>
</Slider.Root>
```

## Value Commit

You can use the `onValueCommit` prop to be notified when the user finishes dragging the thumb and the value changes. This is different than the `onValueChange` callback because it waits until the user stops dragging before calling the callback, where the `onValueChange` callback is called as the user dragging.

```svelte
<Slider.Root
 onValueCommit={(v) => {
  console.log("user is done sliding!", v);
 }}
/>
```

## Multiple Thumbs and Ticks

If the `value` prop has more than one value, the slider will render multiple thumbs. You can also use the `ticks` snippet prop to render ticks at specific intervals

```svelte
<script lang="ts">
 import { Slider } from "bits-ui";
 // we have two numbers in the array, so the slider will render two thumbs
 let value = $state([5, 7]);
</script>
<Slider.Root type="multiple" min={0} max={10} step={1} bind:value>
 {#snippet children({ ticks, thumbs })}
  <Slider.Range />
  {#each thumbs as index}
   <Slider.Thumb {index} />
  {/each}
  {#each ticks as index}
   <Slider.Tick {index} />
  {/each}
 {/snippet}
</Slider.Root>
```

To determine the number of ticks that will be rendered, you can simply divide the `max` value by the `step` value.

## Single Type

Set the `type` prop to `"single"` to allow only one accordion item to be open at a time.

```svelte
<Slider.Root type="single" />
```

```svelte
<script lang="ts">
  import { Slider } from "bits-ui";
  import { cn } from "$lib/utils/styles.js";
  let value = $state(50);
</script>
<div class="w-full md:max-w-[280px]">
  <Slider.Root
    type="single"
    bind:value
    class="relative flex w-full touch-none select-none items-center"
  >
    {#snippet children()}
      <span
        class="bg-dark-10 relative h-2 w-full grow cursor-pointer overflow-hidden rounded-full"
      >
        <Slider.Range class="bg-foreground absolute h-full" />
      </span>
      <Slider.Thumb
        index={0}
        class={cn(
          "border-border-input bg-background hover:border-dark-40 focus-visible:ring-foreground dark:bg-foreground dark:shadow-card focus-visible:outline-hidden block size-[25px] cursor-pointer rounded-full border shadow-sm transition-colors focus-visible:ring-2 focus-visible:ring-offset-2 active:scale-[0.98] disabled:pointer-events-none disabled:opacity-50"
        )}
      />
    {/snippet}
  </Slider.Root>
</div>
```

## Multiple Type

Set the `type` prop to `"multiple"` to allow multiple accordion items to be open at the same time.

```svelte
<Slider.Root type="multiple" />
```

```svelte
<script lang="ts">
  import { Slider } from "bits-ui";
  import { cn } from "$lib/utils/styles.js";
  let value = $state([25, 75]);
</script>
<div class="w-full md:max-w-[280px]">
  <Slider.Root
    type="multiple"
    bind:value
    class="relative flex w-full touch-none select-none items-center"
  >
    {#snippet children({ thumbs })}
      <span
        class="bg-dark-10 relative h-2 w-full grow cursor-pointer overflow-hidden rounded-full"
      >
        <Slider.Range class="bg-foreground absolute h-full" />
      </span>
      {#each thumbs as index}
        <Slider.Thumb
          {index}
          class={cn(
            "border-border-input bg-background hover:border-dark-40 focus-visible:ring-foreground dark:bg-foreground dark:shadow-card focus-visible:outline-hidden block size-[25px] cursor-pointer rounded-full border shadow-sm transition-colors focus-visible:ring-2 focus-visible:ring-offset-2 active:scale-[0.98] disabled:pointer-events-none disabled:opacity-50"
          )}
        />
      {/each}
    {/snippet}
  </Slider.Root>
</div>
```

## Vertical Orientation

You can use the `orientation` prop to change the orientation of the slider, which defaults to `"horizontal"`.

```svelte
<Slider.Root type="single" orientation="vertical">
</Slider.Root>
```

## RTL Support

You can use the `dir` prop to change the reading direction of the slider, which defaults to `"ltr"`.

```svelte
<Slider.Root type="single" dir="rtl">
</Slider.Root>
```

## Auto Sort

By default, the slider will sort the values from smallest to largest, so if you drag a smaller thumb to a larger value, the value of that thumb will be updated to the larger value.

You can disable this behavior by setting the `autoSort` prop to `false`.

```svelte
<Slider.Root type="multiple" autoSort={false}>
</Slider.Root>
```

## HTML Forms

Since there is a near endless number of possible values that a user can select, the slider does not render a hidden input element by default.

You'll need to determine how you want to submit the value(s) of the slider with a form.

Here's an example of how you might do that:

```svelte
<script lang="ts">
 import MySlider from "$lib/components/MySlider.svelte";
 let expectedIncome = $state([50, 100]);
 let desiredIncome = $state(50);
</script>
<form method="POST">
 <MySlider type="multiple" bind:value={expectedIncome} />
 <input type="hidden" name="expectedIncomeStart" value={expectedIncome[0]} />
 <input type="hidden" name="expectedIncomeEnd" value={expectedIncome[1]} />
 <MySlider type="single" bind:value={desiredIncome} />
 <input type="hidden" name="expectedIncomeEnd" value={desiredIncome} />
 <button type="submit">Submit</button>
</form>
```

## API Reference

### Slider.Root

The root slider component which contains the remaining slider components.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` required | `union`- 'single' \| 'multiple'                                      | The type of the slider. If set to `'multiple'`, the slider will allow multiple thumbs and the `value` will be an array of numbers.`Default:  undefined`                                                                                                                                                                                   |
| `value` $bindable                            | `number`                                                                                                                                                                                             | The current value of the slider. If the `type` is set to `'multiple'`, this should be an array of numbers and will default to an empty array.`Default: 0`                                                                                                                                                                                    |
| `onValueChange`                                           | `function`- (value: number) => void \| (value: number\[]) => void    | A callback function called when the value state of the slider changes.`Default:  undefined`                                                                                                                                                                                                                                               |
| `onValueCommit`                                           | `function`- (value: number) => void \| (value: number\[]) => void    | A callback function called when the user finishes dragging the thumb and the value changes. This is different than the `onValueChange` callback because it waits until the user stops dragging before calling the callback, where the `onValueChange` callback is called immediately after the user starts dragging.`Default:  undefined` |
| `disabled`                                                | `boolean`                                                                                                                                                                                            | Whether or not the switch is disabled.`Default: false`                                                                                                                                                                                                                                                                                       |
| `max`                                                     | `number`                                                                                                                                                                                             | The maximum value of the slider.`Default: 100`                                                                                                                                                                                                                                                                                               |
| `min`                                                     | `number`                                                                                                                                                                                             | The minimum value of the slider.`Default: 0`                                                                                                                                                                                                                                                                                                 |
| `orientation`                                             | `enum`- 'horizontal' \| 'vertical'                                   | The orientation of the slider.`Default: 'horizontal'`                                                                                                                                                                                                                                                                                        |
| `step`                                                    | `number`                                                                                                                                                                                             | The step value of the slider.`Default: 1`                                                                                                                                                                                                                                                                                                    |
| `dir`                                                     | `enum`- 'ltr' \| 'rtl'                                               | The reading direction of the app.`Default: 'ltr'`                                                                                                                                                                                                                                                                                            |
| `autoSort`                                                | `boolean`                                                                                                                                                                                            | Whether to automatically sort the values in the array when moving thumbs past one another. This is only applicable to the `'multiple'` type.`Default: true`                                                                                                                                                                                  |
| `ref` $bindable                              | `HTMLSpanElement`                                                                                                                                                                                    | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                                                                                   |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                                                                                                                                                                                      |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                                                                            | | Data Attribute                                   | Value                                                                                                                                                                         | Description                                                                                     |
| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-orientation` | `enum`- '' | The orientation of the slider.                                           |
| `data-slider-root`                                      | `''`                                                                                                                                                                 | Present on the root element. |

### Slider.Range

The range of the slider.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLSpanElement`                                                                                                                                                                                    | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                    | Value         | Description                                                                                       |
| ------------------------------------------------------------------------------------ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-slider-range` | `''` | Present on the range elements. |

### Slider.Thumb

A thumb on the slider.

| Property                                                                                     | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `index` required | `number`                                                                                                                                                                                             | The index of the thumb in the array of thumbs provided by the `thumbs` `children` snippet prop.`Default:  undefined`                                                           |
| `disabled`                                                 | `boolean`                                                                                                                                                                                            | Whether or not the thumb is disabled.`Default: false`                                                                                                                             |
| `ref` $bindable                               | `HTMLSpanElement`                                                                                                                                                                                    | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                 | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                    | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                    | Value         | Description                                                                                       |
| ------------------------------------------------------------------------------------ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-slider-thumb` | `''` | Present on the thumb elements. |

### Slider.Tick

A tick mark on the slider.

| Property                                                                                     | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `index` required | `number`                                                                                                                                                                                             | The index of the tick in the array of ticks provided by the `ticks` `children` snippet prop.`Default:  undefined`                                                              |
| `ref` $bindable                               | `HTMLSpanElement`                                                                                                                                                                                    | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                 | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                    | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                               | Value         | Description                                                                                      |
| ------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-bounded` | `''` | Present when the tick is bounded.                                         |
| `data-slider-tick`                                  | `''` | Present on the tick elements. |

----------------------------------------------------

# Switch Documentation

A toggle control enabling users to switch between "on" and "off" states.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { Label, Switch } from "bits-ui";
</script>
<div class="flex items-center space-x-3">
  <Switch.Root
    id="dnd"
    name="hello"
    class="focus-visible:ring-foreground focus-visible:ring-offset-background data-[state=checked]:bg-foreground data-[state=unchecked]:bg-dark-10 data-[state=unchecked]:shadow-mini-inset dark:data-[state=checked]:bg-foreground focus-visible:outline-hidden peer inline-flex h-[36px] min-h-[36px] w-[60px] shrink-0 cursor-pointer items-center rounded-full px-[3px] transition-colors focus-visible:ring-2 focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50"
  >
    <Switch.Thumb
      class="bg-background data-[state=unchecked]:shadow-mini dark:border-background/30 dark:bg-foreground dark:shadow-popover pointer-events-none block size-[30px] shrink-0 rounded-full transition-transform data-[state=checked]:translate-x-6 data-[state=unchecked]:translate-x-0 dark:border dark:data-[state=unchecked]:border"
    />
  </Switch.Root>
  <Label.Root for="dnd" class="text-sm font-medium">Do not disturb</Label.Root>
</div>
```

## Overview

The Switch component provides an intuitive and accessible toggle control, allowing users to switch between two states, typically "on" and "off". This component is commonly used for enabling or disabling features, toggling settings, or representing boolean values in forms. The Switch offers a more visual and interactive alternative to traditional checkboxes for binary choices.

## Key Features

- **Accessibility**: Built with WAI-ARIA guidelines in mind, ensuring keyboard navigation and screen reader support.  
- **State Management**: Internally manages the on/off state, with options for controlled and uncontrolled usage.  
- **Style-able**: Data attributes allow for smooth transitions between states and custom styles.  
- **HTML Forms**: Can render a hidden input element for form submissions. ## Architecture

The Switch component is composed of two main parts:

- **Root**: The main container component that manages the state and behavior of the switch.  
- **Thumb**: The "movable" part of the switch that indicates the current state. ## Structure

Here's an overview of how the Switch component is structured in code:

```svelte
<script lang="ts">
 import { Switch } from "bits-ui";
</script>
<Switch.Root>
 <Switch.Thumb />
</Switch.Root>
```

## Reusable Components

It's recommended to use the `Switch` primitives to create your own custom switch component that can be used throughout your application.

In the example below, we're using the `Checkbox` and [`Label`](/docs/components/label) components to create a custom switch component.

MySwitch.svelte

```svelte
<script lang="ts">
 import { Switch, Label, useId, type WithoutChildrenOrChild } from "bits-ui";
 let {
  id = useId(),
  checked = $bindable(false),
  ref = $bindable(null),
  ...restProps
 }: WithoutChildrenOrChild<Switch.RootProps> & {
  labelText: string;
 } = $props();
</script>
<Switch.Root bind:checked bind:ref {id} {...restProps}>
 <Switch.Thumb />
</Switch.Root>
<Label.Root for={id}>{labelText}</Label.Root>
```

You can then use the `MySwitch` component in your application like so:

```svelte
<script lang="ts">
 import MySwitch from "$lib/components/MySwitch.svelte";
 let notifications = $state(true);
</script>
<MySwitch bind:checked={notifications} labelText="Enable notifications" />
```

## Managing Checked State

This section covers how to manage the `checked` state of the component.

### Two-Way Binding

Use `bind:checked` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { Switch } from "bits-ui";
 let myChecked = $state(true);
</script>
<button onclick={() => (myChecked = false)}> uncheck </button>
<Switch.Root bind:checked={myChecked} />
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { Switch } from "bits-ui";
 let myChecked = $state(false);
 function getChecked() {
  return myChecked;
 }
 function setChecked(newChecked: boolean) {
  myChecked = newChecked;
 }
</script>
<Switch.Root bind:checked={getChecked, setChecked}>
</Switch.Root>
```

## Disabled State

You can disable the switch by setting the `disabled` prop to `true`.

```svelte
<Switch.Root disabled>
</Switch.Root>
```

## HTML Forms

If you pass the `name` prop to `Switch.Root`, a hidden input element will be rendered to submit the value of the switch to a form.

By default, the input will be submitted with the default checkbox value of `'on'` if the switch is checked.

```svelte
<Switch.Root name="dnd">
</Switch.Root>
```

### Custom Input Value

If you'd prefer to submit a different value, you can use the `value` prop to set the value of the hidden input.

For example, if you wanted to submit a string value, you could do the following:

```svelte
<Switch.Root name="dnd" value="hello">
 <Switch.Thumb />
</Switch.Root>
```

### Required

If you want to make the switch required, you can use the `required` prop.

```svelte
<Switch.Root required>
</Switch.Root>
```

This will apply the `required` attribute to the hidden input element, ensuring that proper form submission is enforced.

## API Reference

### Switch.Root

The root switch component used to set and manage the state of the switch.

| Property                                                                                        | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `checked` $bindable | `boolean`                                                                                                                                                                                            | Whether or not the switch is checked.`Default: false`                                                                                                                             |
| `onCheckedChange`                                             | `function`- (checked: boolean) => void                               | A callback function called when the checked state of the switch changes.`Default:  undefined`                                                                                  |
| `disabled`                                                    | `boolean`                                                                                                                                                                                            | Whether or not the switch is disabled.`Default: false`                                                                                                                            |
| `name`                                                        | `string`                                                                                                                                                                                             | The name of the hidden input element, used to identify the input in form submissions.`Default:  undefined`                                                                     |
| `required`                                                    | `boolean`                                                                                                                                                                                            | Whether or not the switch is required to be checked.`Default: false`                                                                                                              |
| `value`                                                       | `string`                                                                                                                                                                                             | The value of the hidden input element to be used in form submissions when the switch is checked.`Default:  undefined`                                                          |
| `ref` $bindable                                  | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                    | `Snippet`- Snippet                                                   | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                       | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value         | Description                                                                                     |
| ----------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `''` | The switch's checked state.                                              |
| `data-checked`                                    | `''` | Present when the switch is checked.                                      |
| `data-disabled`                                   | `''` | Present when the switch is disabled.                                     |
| `data-switch-root`                                | `''` | Present on the root element. |

### Switch.Thumb

The thumb on the switch used to indicate the switch's state.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLSpanElement`                                                                                                                                                                                    | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`- Snippet                                                   | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value         | Description                                                                                      |
| ----------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-state` | `''` | The switch's checked state.                                               |
| `data-checked`                                    | `''` | Present when the switch is checked.                                       |
| `data-switch-thumb`                               | `''` | Present on the thumb element. |

----------------------------------------------------

# Tabs Documentation

Organizes content into distinct sections, allowing users to switch between them.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { Tabs } from "bits-ui";
  import Airplane from "phosphor-svelte/lib/Airplane";
</script>
<div class="pt-6">
  <Tabs.Root
    value="outbound"
    class="rounded-card border-muted bg-background-alt shadow-card w-[390px] border p-3"
  >
    <Tabs.List
      class="rounded-9px bg-dark-10 shadow-mini-inset dark:bg-background grid w-full grid-cols-2 gap-1 p-1 text-sm font-semibold leading-[0.01em] dark:border dark:border-neutral-600/30"
    >
      <Tabs.Trigger
        value="outbound"
        class="data-[state=active]:shadow-mini dark:data-[state=active]:bg-muted h-8 rounded-[7px] bg-transparent py-2 data-[state=active]:bg-white"
        >Outbound</Tabs.Trigger
      >
      <Tabs.Trigger
        value="inbound"
        class="data-[state=active]:shadow-mini dark:data-[state=active]:bg-muted h-8 rounded-[7px] bg-transparent py-2 data-[state=active]:bg-white"
        >Inbound</Tabs.Trigger
      >
    </Tabs.List>
    <Tabs.Content value="outbound" class="select-none pt-3">
      <div class="grid grid-cols-3 grid-rows-2 gap-0 p-4 pb-1">
        <div class="text-left">
          <h4
            class="mb-2 text-[20px] font-semibold leading-none tracking-[-0.01em]"
          >
            Prague
          </h4>
          <p class="text-muted-foreground text-sm font-medium">06:05</p>
        </div>
        <div class="self-end text-center">
          <p class="text-muted-foreground text-sm font-medium">3h 30m</p>
        </div>
        <div class="text-right">
          <h4
            class="mb-2 text-[20px] font-semibold leading-none tracking-[-0.01em]"
          >
            Malaga
          </h4>
          <p class="text-muted-foreground text-sm font-medium">06:05</p>
        </div>
        <div class="relative col-span-3">
          <hr
            class="border-1 border-border-input relative top-4 h-px border-dashed"
          />
          <div class="bg-background-alt absolute left-1/2 -translate-x-1/2 p-1">
            <Airplane class="text-muted-foreground size-6 rotate-90" />
          </div>
        </div>
      </div>
    </Tabs.Content>
    <Tabs.Content value="inbound" class="select-none pt-3">
      <div class="grid grid-cols-3 grid-rows-2 gap-0 p-4 pb-1">
        <div class="text-left">
          <h4
            class="mb-2 text-[20px] font-semibold leading-none tracking-[-0.01em]"
          >
            Malaga
          </h4>
          <p class="text-muted-foreground text-sm font-medium">07:25</p>
        </div>
        <div class="self-end text-center">
          <p class="text-muted-foreground text-sm font-medium">3h 20m</p>
        </div>
        <div class="text-right">
          <h4
            class="mb-2 text-[20px] font-semibold leading-none tracking-[-0.01em]"
          >
            Prague
          </h4>
          <p class="text-muted-foreground text-sm font-medium">10:45</p>
        </div>
        <div class="relative col-span-3">
          <hr
            class="border-1 border-border-input relative top-4 h-px border-dashed"
          />
          <div class="bg-background-alt absolute left-1/2 -translate-x-1/2 p-1">
            <Airplane class="text-muted-foreground size-6 rotate-90" />
          </div>
        </div>
      </div>
    </Tabs.Content>
  </Tabs.Root>
</div>
```

## Structure

```svelte
<script lang="ts">
 import { Tabs } from "bits-ui";
</script>
<Tabs.Root>
 <Tabs.List>
  <Tabs.Trigger />
 </Tabs.List>
 <Tabs.Content />
</Tabs.Root>
```

## Managing Value State

This section covers how to manage the `value` state of the component.

### Two-Way Binding

Use `bind:value` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { Tabs } from "bits-ui";
 let myValue = $state("");
</script>
<button onclick={() => (myValue = "tab-1")}> Activate tab 1 </button>
<Tabs.Root bind:value={myValue}>
</Tabs.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { Tabs } from "bits-ui";
 let myValue = $state("");
 function getValue() {
  return myValue;
 }
 function setValue(newValue: string) {
  myValue = newValue;
 }
</script>
<Tabs.Root bind:value={getValue, setValue}>
</Tabs.Root>
```

## Orientation

The `orientation` prop is used to determine the orientation of the `Tabs` component, which influences how keyboard navigation will work.

When the `orientation` is set to `'horizontal'`, the `ArrowLeft` and `ArrowRight` keys will move the focus to the previous and next tab, respectively. When the `orientation` is set to `'vertical'`, the `ArrowUp` and `ArrowDown` keys will move the focus to the previous and next tab, respectively.

```svelte
<Tabs.Root orientation="horizontal">
</Tabs.Root>
<Tabs.Root orientation="vertical">
</Tabs.Root>
```

## Activation Mode

By default, the `Tabs` component will automatically activate the tab associated with a trigger when that trigger is focused. This behavior can be disabled by setting the `activationMode` prop to `'manual'`.

When set to `'manual'`, the user will need to activate the tab by pressing the trigger.

```svelte
<Tabs.Root activationMode="manual">
</Tabs.Root>
```

## API Reference

### Tabs.Root

The root tabs component which contains the other tab components.

| Property                                                                                      | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                                                                    |
| -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` $bindable | `string`                                                                                                                                                                                             | The active tab value.`Default:  undefined`                                                                                                                                                                                    |
| `onValueChange`                                             | `function`- (value: string) => void                                  | A callback function called when the active tab value changes.`Default:  undefined`                                                                                                                                            |
| `activationMode`                                            | `enum`- 'automatic' \| 'manual'                                      | How the activation of tabs should be handled. If set to `'automatic'`, the tab will be activated when the trigger is focused. If set to `'manual'`, the tab will be activated when the trigger is pressed.`Default: 'automatic'` |
| `disabled`                                                  | `boolean`                                                                                                                                                                                            | Whether or not the tabs are disabled.`Default: false`                                                                                                                                                                            |
| `loop`                                                      | `boolean`                                                                                                                                                                                            | Whether or not the tabs should loop when navigating with the keyboard.`Default: true`                                                                                                                                            |
| `orientation`                                               | `enum`- 'horizontal' \| 'vertical'                                   | The orientation of the tabs.`Default: horizontal`                                                                                                                                                                                |
| `ref` $bindable                                | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                       |
| `children`                                                  | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                                                                          |
| `child`                                                     | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                | | Data Attribute                                   | Value                                                                                                                                                                         | Description                                                                                     |
| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-orientation` | `enum`- '' | The orientation of the tabs.                                             |
| `data-tabs-root`                                        | `''`                                                                                                                                                                 | Present on the root element. |

### Tabs.List

The component containing the tab triggers.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                   | Value                                                                                                                                                                         | Description                                                                                     |
| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-orientation` | `enum`- '' | The orientation of the tabs.                                             |
| `data-tabs-list`                                        | `''`                                                                                                                                                                 | Present on the list element. |

### Tabs.Trigger

The trigger for a tab.

| Property                                                                                     | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` required | `string`                                                                                                                                                                                             | The value of the tab this trigger represents.`Default:  undefined`                                                                                                             |
| `disabled`                                                 | `boolean`                                                                                                                                                                                            | Whether or not the tab is disabled.`Default: false`                                                                                                                               |
| `ref` $bindable                               | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                 | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                    | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value                                                                                                                                                                         | Description                                                                                         |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- '' | The state of the tab trigger.                                                |
| `data-value`                                      | `''`                                                                                                                                                                 | The value of the tab this trigger represents.                                |
| `data-orientation`                                | `enum`- '' | The orientation of the tabs.                                                 |
| `data-disabled`                                   | `''`                                                                                                                                                                 | Present when the tab trigger is disabled.                                    |
| `data-tabs-trigger`                               | `''`                                                                                                                                                                 | Present on the trigger elements. |

### Tabs.Content

The panel containing the contents of a tab.

| Property                                                                                     | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` required | `string`                                                                                                                                                                                             | The value of the tab this content represents.`Default:  undefined`                                                                                                             |
| `ref` $bindable                               | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                 | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                    | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                    | Value         | Description                                                                                         |
| ------------------------------------------------------------------------------------ | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-tabs-content` | `''` | Present on the content elements. |

----------------------------------------------------

# Toggle Group Documentation

Groups multiple toggle controls, allowing users to enable one or multiple options.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { ToggleGroup } from "bits-ui";
  import TextB from "phosphor-svelte/lib/TextB";
  import TextItalic from "phosphor-svelte/lib/TextItalic";
  import TextStrikethrough from "phosphor-svelte/lib/TextStrikethrough";
  let value: string[] = $state(["bold"]);
</script>
<ToggleGroup.Root
  bind:value
  type="multiple"
  class="h-input rounded-card-sm border-border bg-background-alt shadow-mini flex items-center gap-x-0.5 border px-[4px] py-1"
>
  <ToggleGroup.Item
    aria-label="toggle bold"
    value="bold"
    class="rounded-9px bg-background-alt hover:bg-muted active:bg-dark-10 data-[state=on]:bg-muted data-[state=off]:text-foreground-alt data-[state=on]:text-foreground active:data-[state=on]:bg-dark-10 inline-flex size-10 items-center justify-center transition-all active:scale-[0.98]"
  >
    <TextB class="size-6" />
  </ToggleGroup.Item>
  <ToggleGroup.Item
    aria-label="toggle italic"
    value="italic"
    class="rounded-9px bg-background-alt hover:bg-muted active:bg-dark-10 data-[state=on]:bg-muted data-[state=off]:text-foreground-alt data-[state=on]:text-foreground active:data-[state=on]:bg-dark-10 inline-flex size-10 items-center justify-center transition-all active:scale-[0.98]"
  >
    <TextItalic class="size-6" />
  </ToggleGroup.Item>
  <ToggleGroup.Item
    aria-label="toggle strikethrough"
    value="strikethrough"
    class="rounded-9px bg-background-alt hover:bg-muted active:bg-dark-10 data-[state=on]:bg-muted data-[state=off]:text-foreground-alt data-[state=on]:text-foreground active:data-[state=on]:bg-dark-10 inline-flex size-10 items-center justify-center transition-all active:scale-[0.98]"
  >
    <TextStrikethrough class="size-6" />
  </ToggleGroup.Item>
</ToggleGroup.Root>
```

## Structure

```svelte
<script lang="ts">
 import { ToggleGroup } from "bits-ui";
</script>
<ToggleGroup.Root>
 <ToggleGroup.Item value="bold">bold</ToggleGroup.Item>
 <ToggleGroup.Item value="italic">italic</ToggleGroup.Item>
</ToggleGroup.Root>
```

## Single & Multiple

The `ToggleGroup` component supports two `type` props, `'single'` and `'multiple'`. When the `type` is set to `'single'`, the `ToggleGroup` will only allow a single item to be selected at a time, and the type of the `value` prop will be a string.

When the `type` is set to `'multiple'`, the `ToggleGroup` will allow multiple items to be selected at a time, and the type of the `value` prop will be an array of strings.

## Managing Value State

This section covers how to manage the `value` state of the component.

### Two-Way Binding

Use `bind:value` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { ToggleGroup } from "bits-ui";
 let myValue = $state("");
</script>
<button onclick={() => (myValue = "item-1")}> Press item 1 </button>
<ToggleGroup.Root type="single" bind:value={myValue}>
</ToggleGroup.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { ToggleGroup } from "bits-ui";
 let myValue = $state("");
 function getValue() {
  return myValue;
 }
 function setValue(newValue: string) {
  myValue = newValue;
 }
</script>
<ToggleGroup.Root type="single" bind:value={getValue, setValue}>
</ToggleGroup.Root>
```

## API Reference

### ToggleGroup.Root

The root component which contains the toggle group items.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` required | `enum`- 'single' \| 'multiple'                                       | The type of toggle group.`Default:  undefined`                                                                                                                                 |
| `value` $bindable                            | `union`- string \| string\[]                                         | The value of the toggle group. If the `type` is `'multiple'`, this will be an array of strings, otherwise it will be a string.`Default:  undefined`                            |
| `onValueChange`                                           | `function`- (value: string) => void \| (value: string\[]) => void    | A callback function called when the value of the toggle group changes. The type of the value is dependent on the type of the toggle group.`Default:  undefined`                |
| `disabled`                                                | `boolean`                                                                                                                                                                                            | Whether or not the switch is disabled.`Default: false`                                                                                                                            |
| `loop`                                                    | `boolean`                                                                                                                                                                                            | Whether or not the toggle group should loop when navigating.`Default: true`                                                                                                       |
| `orientation`                                             | `enum`- 'horizontal' \| 'vertical'                                   | The orientation of the toggle group.`Default: horizontal`                                                                                                                         |
| `rovingFocus`                                             | `boolean`                                                                                                                                                                                            | Whether or not the toggle group should use roving focus when navigating.`Default: true`                                                                                           |
| `ref` $bindable                              | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                   | Value                                                                                                                                                                         | Description                                                                                     |
| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-orientation` | `enum`- '' | The orientation of the toggle group.                                     |
| `data-toggle-group-root`                                | `''`                                                                                                                                                                 | Present on the root element. |

### ToggleGroup.Item

An individual toggle item within the group.

| Property                                                               | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` | `string`                                                                                                                                                                                             | The value of the item.`Default:  undefined`                                                                                                                                    |
| `disabled`                           | `boolean`                                                                                                                                                                                            | Whether or not the switch is disabled.`Default: false`                                                                                                                            |
| `ref` $bindable         | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                           | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                              | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value                                                                                                                                                                         | Description                                                                                          |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- '' | Whether the toggle item is in the on or off state.                            |
| `data-value`                                      | `''`                                                                                                                                                                 | The value of the toggle item.                                                 |
| `data-orientation`                                | `enum`- '' | The orientation of the toggle group.                                          |
| `data-disabled`                                   | `''`                                                                                                                                                                 | Present when the toggle item is disabled.                                     |
| `data-toggle-group-item`                          | `''`                                                                                                                                                                 | Present on the toggle group item. |

----------------------------------------------------

# Toggle Documentation

A control element that switches between two states, providing a binary choice.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { Toggle } from "bits-ui";
  import LockKeyOpen from "phosphor-svelte/lib/LockKeyOpen";
  let unlocked = $state(false);
  const code = $derived(unlocked ? "B1T5" : "");
</script>
<div
  class="min-h-input rounded-card-sm border-border bg-background-alt shadow-mini flex h-full w-[176px] items-center gap-2 border py-1 pl-[18px] pr-1.5"
>
  <div
    class="font-alt text-end text-[19px] tracking-[13.87px] {unlocked
      ? 'text-foreground'
      : 'text-muted-foreground'}"
  >
    {code}
  </div>
  <Toggle.Root
    aria-label="toggle code visibility"
    class="bg-background-alt hover:bg-muted active:bg-dark-10 data-[state=on]:bg-muted data-[state=off]:text-foreground-alt data-[state=on]:text-foreground active:data-[state=on]:bg-dark-10 inline-flex size-10 items-center justify-center rounded-[9px] transition-all active:scale-[0.98]"
    bind:pressed={unlocked}
  >
    <LockKeyOpen class="size-6" />
  </Toggle.Root>
</div>
```

## Structure

```svelte
<script lang="ts">
 import { Toggle } from "bits-ui";
</script>
<Toggle.Root />
```

## Managing Pressed State

This section covers how to manage the `pressed` state of the component.

### Two-Way Binding

Use `bind:pressed` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { Toggle } from "bits-ui";
 let myPressed = $state(true);
</script>
<button onclick={() => (myPressed = false)}> un-press </button>
<Toggle.Root bind:pressed={myPressed} />
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { Toggle } from "bits-ui";
 let myPressed = $state(false);
 function getPressed() {
  return myPressed;
 }
 function setPressed(newPressed: boolean) {
  myPressed = newPressed;
 }
</script>
<Toggle.Root bind:pressed={getPressed, setPressed}>
</Toggle.Root>
```

## API Reference

### Toggle.Root

The toggle button.

| Property                                                                                        | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pressed` $bindable | `boolean`                                                                                                                                                                                            | Whether or not the toggle button is pressed.`Default: false`                                                                                                                      |
| `onPressedChange`                                             | `function`- (pressed: boolean) => void                               | A callback function called when the pressed state of the toggle changes.`Default:  undefined`                                                                                  |
| `disabled`                                                    | `boolean`                                                                                                                                                                                            | Whether or not the switch is disabled.`Default: false`                                                                                                                            |
| `ref` $bindable                                  | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                    | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                       | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value                                                                                                                                                                         | Description                                                                                     |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- '' | Whether the toggle is in the on or off state.                            |
| `data-disabled`                                   | `''`                                                                                                                                                                 | Present when the toggle is disabled.                                     |
| `data-toggle-root`                                | `''`                                                                                                                                                                 | Present on the root element. |

----------------------------------------------------

# Toolbar Documentation

Displays frequently used actions or tools in a compact, easily accessible bar.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { Separator, Toolbar } from "bits-ui";
  import Sparkle from "phosphor-svelte/lib/Sparkle";
  import TextAlignCenter from "phosphor-svelte/lib/TextAlignCenter";
  import TextAlignLeft from "phosphor-svelte/lib/TextAlignLeft";
  import TextAlignRight from "phosphor-svelte/lib/TextAlignRight";
  import TextB from "phosphor-svelte/lib/TextB";
  import TextItalic from "phosphor-svelte/lib/TextItalic";
  import TextStrikethrough from "phosphor-svelte/lib/TextStrikethrough";
  let text = $state(["bold"]);
  let align = $state("");
</script>
<Toolbar.Root
  class="rounded-10px border-border bg-background-alt shadow-mini flex h-12 min-w-max items-center justify-center border px-[4px] py-1"
>
  <Toolbar.Group
    bind:value={text}
    type="multiple"
    class="flex items-center gap-x-0.5"
  >
    <Toolbar.GroupItem
      aria-label="toggle bold"
      value="bold"
      class="rounded-9px bg-background-alt text-foreground/60 hover:bg-muted active:bg-dark-10 data-[state=on]:bg-muted data-[state=on]:text-foreground/80 active:data-[state=on]:bg-dark-10 inline-flex size-10 items-center justify-center transition-all active:scale-[0.98]"
    >
      <TextB class="size-6" />
    </Toolbar.GroupItem>
    <Toolbar.GroupItem
      aria-label="toggle italic"
      value="italic"
      class="rounded-9px bg-background-alt text-foreground/60 hover:bg-muted active:bg-dark-10 data-[state=on]:bg-muted data-[state=on]:text-foreground/80 active:data-[state=on]:bg-dark-10 inline-flex size-10 items-center justify-center transition-all active:scale-[0.98]"
    >
      <TextItalic class="size-6" />
    </Toolbar.GroupItem>
    <Toolbar.GroupItem
      aria-label="toggle strikethrough"
      value="strikethrough"
      class="rounded-9px bg-background-alt text-foreground/60 hover:bg-muted active:bg-dark-10 data-[state=on]:bg-muted data-[state=on]:text-foreground/80 active:data-[state=on]:bg-dark-10 inline-flex size-10 items-center justify-center transition-all active:scale-[0.98]"
    >
      <TextStrikethrough class="size-6" />
    </Toolbar.GroupItem>
  </Toolbar.Group>
  <Separator.Root class="bg-dark-10 -my-1 mx-1 w-[1px] self-stretch" />
  <Toolbar.Group
    bind:value={align}
    type="single"
    class="flex items-center gap-x-0.5"
  >
    <Toolbar.GroupItem
      aria-label="align left"
      value="left"
      class="rounded-9px bg-background-alt text-foreground/60 hover:bg-muted active:bg-dark-10 data-[state=on]:bg-muted data-[state=on]:text-foreground/80 active:data-[state=on]:bg-dark-10 inline-flex size-10 items-center justify-center transition-all active:scale-[0.98]"
    >
      <TextAlignLeft class="size-6" />
    </Toolbar.GroupItem>
    <Toolbar.GroupItem
      aria-label="align center"
      value="center"
      class="rounded-9px bg-background-alt text-foreground/60 hover:bg-muted active:bg-dark-10 data-[state=on]:bg-muted data-[state=on]:text-foreground/80 active:data-[state=on]:bg-dark-10 inline-flex size-10 items-center justify-center transition-all active:scale-[0.98]"
    >
      <TextAlignCenter class="size-6" />
    </Toolbar.GroupItem>
    <Toolbar.GroupItem
      aria-label="align right"
      value="right"
      class="rounded-9px bg-background-alt text-foreground/60 hover:bg-muted active:bg-dark-10 data-[state=on]:bg-muted data-[state=on]:text-foreground/80 active:data-[state=on]:bg-dark-10 inline-flex size-10 items-center justify-center transition-all active:scale-[0.98]"
    >
      <TextAlignRight class="size-6" />
    </Toolbar.GroupItem>
  </Toolbar.Group>
  <Separator.Root class="bg-dark-10 -my-1 mx-1 w-[1px] self-stretch" />
  <div class="flex items-center">
    <Toolbar.Button
      class="rounded-9px text-foreground/80 hover:bg-muted active:bg-dark-10 inline-flex items-center justify-center  px-3 py-2 text-sm font-medium transition-all active:scale-[0.98]"
    >
      <Sparkle class="mr-2 size-6" />
      <span> Ask AI </span>
    </Toolbar.Button>
  </div>
</Toolbar.Root>
```

## Structure

```svelte
<script lang="ts">
 import { Toolbar } from "bits-ui";
</script>
<Toolbar.Root>
 <Toolbar.Group>
  <Toolbar.GroupItem />
 </Toolbar.Group>
 <Toolbar.Link />
 <Toolbar.Button />
</Toolbar.Root>
```

## Managing Value State

This section covers how to manage the `value` state of the component.

### Two-Way Binding

Use `bind:value` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { Toolbar } from "bits-ui";
 let myValue = $state("");
</script>
<button onclick={() => (myValue = "item-1")}> Press item 1 </button>
<Toolbar.Root>
 <Toolbar.Group type="single" bind:value={myValue}>
 </Toolbar.Group>
</Toolbar.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { Toolbar } from "bits-ui";
 let myValue = $state("");
 function getValue() {
  return myValue;
 }
 function setValue(newValue: string) {
  myValue = newValue;
 }
</script>
<Toolbar.Root>
 <Toolbar.Group type="single" bind:value={getValue, setValue}>
 </Toolbar.Group>
</Toolbar.Root>
```

## API Reference

### Toolbar.Root

The root component which contains the toolbar.

| Property                                                              | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `loop` | `boolean`                                                                                                                                                                                            | Whether or not the toolbar should loop when navigating.`Default: true`                                                                                                            |
| `orientation`                       | `enum`- 'horizontal' \| 'vertical'                                    | The orientation of the toolbar.`Default: horizontal`                                                                                                                              |
| `ref` $bindable        | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                          | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                             | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                   | Value                                                                                                                                                                                                 | Description                                                                                     |
| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-orientation` | `enum`- 'vertical' \| 'horizontal' | The orientation of the component.                                        |
| `data-toolbar-root`                                     | `''`                                                                                                                                                                                         | Present on the root element. |

### Toolbar.Button

A button in the toolbar.

| Property                                                                  | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `disabled` | `boolean`                                                                                                                                                                                            | Whether or not the button is disabled.`Default: false`                                                                                                                            |
| `ref` $bindable            | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                              | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                 | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                      | Value         | Description                                                                                       |
| -------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-toolbar-button` | `''` | Present on the button element. |

### Toolbar.Link

A link in the toolbar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLAnchorElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                    | Value         | Description                                                                                     |
| ------------------------------------------------------------------------------------ | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-toolbar-link` | `''` | Present on the link element. |

### Toolbar.Group

A group of toggle items in the toolbar.

| Property                                                                                    | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` required | `enum`- 'single' \| 'multiple'                                       | The type of toggle group.`Default: 'single'`                                                                                                                                      |
| `value` $bindable                            | `union`- string \| string\[]                                         | The value of the toggle group. If the type is multiple, this will be an array of strings, otherwise it will be a string.`Default:  undefined`                                  |
| `onValueChange`                                           | `function`- (value: string) => void \| (value: string\[]) => void    | A callback function called when the value changes.`Default:  undefined`                                                                                                        |
| `disabled`                                                | `boolean`                                                                                                                                                                                            | Whether or not the switch is disabled.`Default: false`                                                                                                                            |
| `ref` $bindable                              | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                                                | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                                   | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                                     | Value         | Description                                                                                      |
| ------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-toolbar-group` | `''` | Present on the group element. |

### Toolbar.GroupItem

A toggle item in the toolbar toggle group.

| Property                                                                                     | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                                                                                                                         |
| ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` required | `string`                                                                                                                                                                                             | The value of the toolbar toggle group item. When the toolbar toggle group item is selected, toolbar the toggle group's value will be set to this value if in single mode, or this value will be pushed to the toggle group's array value if in multiple mode.`Default:  undefined` |
| `disabled`                                                 | `boolean`                                                                                                                                                                                            | Whether or not the item is disabled.`Default: false`                                                                                                                                                                                                                                  |
| `ref` $bindable                               | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                            |
| `children`                                                 | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                                                                                                                               |
| `child`                                                    | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                     | | Data Attribute                             | Value                                                                                                                                                                         | Description                                                                                            |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-state` | `enum`- '' | Whether the toolbar toggle item is in the on or off state.                      |
| `data-value`                                      | `''`                                                                                                                                                                 | The value of the toolbar toggle item.                                           |
| `data-disabled`                                   | `''`                                                                                                                                                                 | Present when the toolbar toggle item is disabled.                               |
| `data-toolbar-item`                               | `''`                                                                                                                                                                 | Present on the toolbar toggle item. |

----------------------------------------------------

# Tooltip Documentation

Provides additional information or context when users hover over or interact with an element.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<script lang="ts">
  import { Tooltip } from "bits-ui";
  import MagicWand from "phosphor-svelte/lib/MagicWand";
</script>
<Tooltip.Provider>
  <Tooltip.Root delayDuration={200}>
    <Tooltip.Trigger
      class="border-border-input bg-background-alt shadow-btn ring-dark ring-offset-background
  hover:bg-muted focus-visible:ring-dark focus-visible:ring-offset-background focus-visible:outline-hidden inline-flex size-10 items-center justify-center rounded-full border focus-visible:ring-2 focus-visible:ring-offset-2"
    >
      <MagicWand class="size-5" />
    </Tooltip.Trigger>
    <Tooltip.Content sideOffset={8}>
      <div
        class="rounded-input border-dark-10 bg-background shadow-popover outline-hidden z-0 flex items-center justify-center border p-3 text-sm font-medium"
      >
        Make some magic!
      </div>
    </Tooltip.Content>
  </Tooltip.Root>
</Tooltip.Provider>
```

## Structure

```svelte
<script lang="ts">
 import { Tooltip } from "bits-ui";
</script>
<Tooltip.Provider>
 <Tooltip.Root>
  <Tooltip.Trigger />
  <Tooltip.Portal>
   <Tooltip.Content>
    <Tooltip.Arrow />
   </Tooltip.Content>
  </Tooltip.Portal>
 </Tooltip.Root>
</Tooltip.Provider>
```

## Provider Component

The `Tooltip.Provider` component is required to be an ancestor of the `Tooltip.Root` component. It provides shared state for the tooltip components used within it. You can set a single `delayDuration` or `disableHoverableContent` prop on the provider component to apply to all the tooltip components within it.

```svelte
<script lang="ts">
 import { Tooltip } from "bits-ui";
</script>
<Tooltip.Provider delayDuration={0} disableHoverableContent={true}>
 <Tooltip.Root>
  <Tooltip.Trigger />
  <Tooltip.Portal>
   <Tooltip.Content>
    <Tooltip.Arrow />
   </Tooltip.Content>
  </Tooltip.Portal>
 </Tooltip.Root>
 <Tooltip.Root>
  <Tooltip.Trigger />
  <Tooltip.Portal>
   <Tooltip.Content>
    <Tooltip.Arrow />
   </Tooltip.Content>
  </Tooltip.Portal>
 </Tooltip.Root>
</Tooltip.Provider>
```

It also ensures that only a single tooltip within the same provider can be open at a time. It's recommended to wrap your root layout content with the provider component, setting your sensible default props there.

+layout.svelte

```svelte
<script lang="ts">
 import { Tooltip } from "bits-ui";
 let { children } = $props();
</script>
<Tooltip.Provider>
 {@render children()}
</Tooltip.Provider>
```

## Managing Open State

This section covers how to manage the `open` state of the component.

### Two-Way Binding

Use `bind:open` for simple, automatic state synchronization:

```svelte
<script lang="ts">
 import { Tooltip } from "bits-ui";
 let isOpen = $state(false);
</script>
<button onclick={() => (isOpen = true)}>Open Tooltip</button>
<Tooltip.Root bind:open={isOpen}>
</Tooltip.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
 import { Tooltip } from "bits-ui";
 let myOpen = $state(false);
 function getOpen() {
  return myOpen;
 }
 function setOpen(newOpen: boolean) {
  myOpen = newOpen;
 }
</script>
<Tooltip.Root bind:open={getOpen, setOpen}>
</Tooltip.Root>
```

## Mobile Tooltips

Tooltips are *not* supported on mobile devices. The intent of a tooltip is to provide a "tip" about a "tool" before the user interacts with that tool (in most cases, a button).

This is not possible on mobile devices, because there is no sense of hover on mobile. If a user were to press/touch a button with a tooltip, the action that button triggers would be taken before they were even able to see the tooltip, which renders it useless.

If you are using a tooltip on a button without an action, you should consider using a [Popover](/docs/components/popover) instead.

If you'd like to learn more about how we came to this decision, here are some useful resources:

> 
>
> The tooltip is not the appropriate role for the more information "i" icon, . A tooltip is directly associated with the owning element. The  isn't 'described by' detailed information; the tool or control is.
>
> 
>
> 
>
> [MDN ARIA Tooltips](https://arc.net/l/quote/zfvjgalg)
>
> 
>
> 

> 
>
> Tooltips should only ever contain non-essential content. The best approach to writing tooltip content is to always assume it may never be read.
>
> 
>
> 
>
> [Tooltips in the time of WCAG 2.1](https://arc.net/l/quote/gdrkepxb)
>
> 
>
> 

## Reusable Components

It's recommended to use the `Tooltip` primitives to build your own custom tooltip component that can be used throughout your application.

Below is an example of how you might create a reusable tooltip component that can be used throughout your application. Of course, this isn't the only way to do it, but it should give you a good idea of how to compose the primitives.

MyTooltip.svelte

```svelte
<script lang="ts">
 import { Tooltip } from "bits-ui";
 import { type Snippet } from "svelte";
 type Props = Tooltip.RootProps & {
  trigger: Snippet;
  triggerProps?: Tooltip.TriggerProps;
 };
 let {
  open = $bindable(false),
  children,
  buttonText,
  triggerProps = {},
  ...restProps
 }: Tooltip.RootProps = $props();
</script>

<Tooltip.Root bind:open {onOpenChange}>
 <Tooltip.Trigger {...triggerProps}>
  {@render trigger()}
 </Tooltip.Trigger>
 <Tooltip.Portal>
  <Tooltip.Content>
   <Tooltip.Arrow />
   {@render children?.()}
  </Tooltip.Content>
 </Tooltip.Portal>
</Tooltip.Root>
```

You could then use the `MyTooltip` component in your application like so:

+page.svelte

```svelte
<script lang="ts">
 import MyTooltip from "$lib/components/MyTooltip.svelte";
 import BoldIcon from "..some-icon-library"; // not real
</script>
<MyTooltip triggerProps={{ onclick: () => alert("changed to bold!") }}>
 {#snippet trigger()}
  <BoldIcon />
 {/snippet}
 Change font to bold
</MyTooltip>
```

## Delay Duration

You can change how long a user needs to hover over a trigger before the tooltip appears by setting the `delayDuration` prop on the `Tooltip.Root` or `Tooltip.Provider` component.

```svelte
<Tooltip.Root delayDuration={200}>
</Tooltip.Root>
```

## Close on Trigger Click

By default, the tooltip will close when the user clicks the trigger. If you want to disable this behavior, you can set the `disableCloseOnTriggerClick` prop to `true`.

```svelte
<Tooltip.Root disableCloseOnTriggerClick>
</Tooltip.Root>
```

## Hoverable Content

By default, the tooltip will remain open when the user hovers over the content. If you instead want the tooltip to close as the user moves their mouse towards the content, you can set the `disableHoverableContent` prop to `true`.

```svelte
<Tooltip.Root disableHoverableContent>
</Tooltip.Root>
```

## Non-Keyboard Focus

If you want to prevent opening the tooltip when the user focuses the trigger without using the keyboard, you can set the `ignoreNonKeyboardFocus` prop to `true`.

```svelte
<Tooltip.Root ignoreNonKeyboardFocus>
</Tooltip.Root>
```

## Svelte Transitions

You can use the `forceMount` prop along with the `child` snippet to forcefully mount the `Tooltip.Content` component to use Svelte Transitions or another animation library that requires more control.

```svelte
<script lang="ts">
 import { Tooltip } from "bits-ui";
 import { fly, fade } from "svelte/transition";
</script>
<Tooltip.Root>
 <Tooltip.Content forceMount>
  {#snippet child({ wrapperProps, props, open })}
   {#if open}
    <div {...wrapperProps}>
     <div {...props} transition:fly>
     </div>
    </div>
   {/if}
  {/snippet}
 </Tooltip.Content>
</Dialog.Root>
```

Of course, this isn't the prettiest syntax, so it's recommended to create your own reusable content components that handles this logic if you intend to use this approach throughout your app. For more information on using transitions with Bits UI components, see the [Transitions](/docs/transitions) documentation.

```svelte
<script lang="ts">
  import { Tooltip } from "bits-ui";
  import MagicWand from "phosphor-svelte/lib/MagicWand";
  import { fly } from "svelte/transition";
</script>
<Tooltip.Provider>
  <Tooltip.Root delayDuration={200}>
    <Tooltip.Trigger
      class="border-border-input bg-background-alt shadow-btn ring-dark ring-offset-background
  hover:bg-muted focus-visible:ring-dark focus-visible:ring-offset-background focus-visible:outline-hidden inline-flex size-10 items-center justify-center rounded-full border focus-visible:ring-2 focus-visible:ring-offset-2"
    >
      <MagicWand class="size-5" />
    </Tooltip.Trigger>
    <Tooltip.Content sideOffset={8} forceMount>
      {#snippet child({ wrapperProps, props, open })}
        {#if open}
          <div {...wrapperProps}>
            <div {...props} transition:fly={{ duration: 300 }}>
              <div
                class="rounded-input border-dark-10 bg-background shadow-popover outline-hidden z-0 flex items-center justify-center border p-3 text-sm font-medium"
              >
                Make some magic!
              </div>
            </div>
          </div>
        {/if}
      {/snippet}
    </Tooltip.Content>
  </Tooltip.Root>
</Tooltip.Provider>
```

## Opt-out of Floating UI

When you use the `Tooltip.Content` component, Bits UI uses [Floating UI](https://floating-ui.com/) to position the content relative to the trigger, similar to other popover-like components.

You can opt-out of this behavior by instead using the `Tooltip.ContentStatic` component. This component does not use Floating UI and leaves positioning the content entirely up to you.

```svelte
<Tooltip.Root>
 <Tooltip.Trigger>Hello</Tooltip.Trigger>
 <Tooltip.ContentStatic>
 </Tooltip.ContentStatic>
</Tooltip.Root>
```

##### Note

When using the `Tooltip.ContentStatic` component, the `Tooltip.Arrow` component will not be rendered relative to it as it is designed to be used with `Tooltip.Content`.

## Custom Anchor

By default, the `Tooltip.Content` is anchored to the `Tooltip.Trigger` component, which determines where the content is positioned.

If you wish to instead anchor the content to a different element, you can pass either a selector `string` or an `HTMLElement` to the `customAnchor` prop of the `Tooltip.Content` component.

```svelte
<script lang="ts">
 import { Tooltip } from "bits-ui";
 let customAnchor = $state<HTMLElement>(null!);
</script>
<div bind:this={customAnchor}></div>
<Tooltip.Root>
 <Tooltip.Trigger />
 <Tooltip.Content {customAnchor}>
 </Tooltip.Content>
</Tooltip.Root>
```

## API Reference

### Tooltip.Provider

A provider component which contains shared state and logic for the tooltips within its subtree.

| Property                                                                       | Type                                                 | Description                                                                                                                                                                             |
| ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `delayDuration` | `number`  | The amount of time in milliseconds to delay opening the tooltip when hovering over the trigger.`Default: 700`                                             |
| `disableHoverableContent`                    | `boolean` | Whether or not to disable the hoverable content. This is useful when the content contains interactive elements.`Default: false`                           |
| `disabled`                                   | `boolean` | Whether or not the tooltip is disabled.`Default: false`                                                                                                   |
| `disableCloseOnTriggerClick`                 | `boolean` | Whether or not to close the tooltip when pressing the escape key. This is useful when the content contains interactive elements.`Default: false`          |
| `skipDelayDuration`                          | `number`  | The amount of time in milliseconds to delay opening the tooltip when the user has used their mouse to hover over the trigger.`Default: 300`               |
| `ignoreNonKeyboardFocus`                     | `boolean` | Whether or not to ignore the tooltip when the focus is not on the trigger. This is useful when the content contains interactive elements.`Default: false` |
| `children`                                   | `Snippet` | The children content to render.`Default:  undefined`                                                               |

### Tooltip.Root

The root component containing the parts of the tooltip. Must be a descendant of a `Tooltip.Provider` component.

| Property                                                                                     | Type                                                                                                                                                                                                           | Description                                                                                                                                                                             |
| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `open` $bindable | `boolean`                                                                                                                                                           | The open state of the tooltip component.`Default: false`                                                                                                  |
| `onOpenChange`                                             | `function`- (open: boolean) => void | A callback that fires when the open state changes.`Default:  undefined`                                                                                |
| `disabled`                                                 | `boolean`                                                                                                                                                           | Whether or not the tooltip is disabled.`Default: false`                                                                                                   |
| `delayDuration`                                            | `number`                                                                                                                                                            | The amount of time in milliseconds to delay opening the tooltip when hovering over the trigger.`Default: 700`                                             |
| `disableHoverableContent`                                  | `boolean`                                                                                                                                                           | Whether or not to disable the hoverable content. This is useful when the content contains interactive elements.`Default: false`                           |
| `disableCloseOnTriggerClick`                               | `boolean`                                                                                                                                                           | Whether or not to close the tooltip when pressing the escape key. This is useful when the content contains interactive elements.`Default: false`          |
| `ignoreNonKeyboardFocus`                                   | `boolean`                                                                                                                                                           | Whether or not to ignore the tooltip when the focus is not on the trigger. This is useful when the content contains interactive elements.`Default: false` |
| `children`                                                 | `Snippet`                                                                                                                                                           | The children content to render.`Default:  undefined`                                                               |

### Tooltip.Trigger

A component which triggers the opening and closing of the tooltip on hover or focus.

| Property                                                                  | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `disabled` | `boolean`                                                                                                                                                                                            | Whether or not the tooltip trigger is disabled.`Default: false`                                                                                                                   |
| `ref` $bindable            | `HTMLButtonElement`                                                                                                                                                                                  | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                              | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                                 | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value                                                                                                      | Description                                                                                                |
| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum` | Whether the tooltip is open or closed.                                              |
| `data-tooltip-trigger`                            | `''`                                                                                              | Present on the tooltip trigger element. |

### Tooltip.Content

The contents of the tooltip which are displayed when the tooltip is open.

| Property                                                              | Type                                                                                                                                                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `side` | `enum`- 'top' \| 'bottom' \| 'left' \| 'right'                                     | The preferred side of the anchor to render the floating element against when open. Will be reversed when collisions occur.`Default: bottom`                                                                                                                                                                                                                                                                                        |
| `sideOffset`                        | `number`                                                                                                                                                                                                           | The distance in pixels from the anchor to the floating element.`Default: 0`                                                                                                                                                                                                                                                                                                                                                        |
| `align`                             | `enum`- 'start' \| 'center' \| 'end'                                               | The preferred alignment of the anchor to render the floating element against when open. This may change when collisions occur.`Default: start`                                                                                                                                                                                                                                                                                     |
| `alignOffset`                       | `number`                                                                                                                                                                                                           | The distance in pixels from the anchor to the floating element.`Default: 0`                                                                                                                                                                                                                                                                                                                                                        |
| `arrowPadding`                      | `number`                                                                                                                                                                                                           | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0`                                                                                                                                                                                                                                                                                                  |
| `avoidCollisions`                   | `boolean`                                                                                                                                                                                                          | When `true`, overrides the `side` and `align` options to prevent collisions with the boundary edges.`Default: true`                                                                                                                                                                                                                                                                                                                |
| `collisionBoundary`                 | `union`- Element \| null                                                           | A boundary element or array of elements to check for collisions against.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                   |
| `collisionPadding`                  | `union`- number \| Partial\&lt;Record\&lt;Side, number\&gt;\&gt;                   | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0`                                                                                                                                                                                                                                                                                                  |
| `sticky`                            | `enum`- 'partial' \| 'always'                                                      | The sticky behavior on the align axis. `'partial'` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst `'always'` will keep the content in the boundary regardless.`Default: partial`                                                                                                                                                                                        |
| `hideWhenDetached`                  | `boolean`                                                                                                                                                                                                          | When `true`, hides the content when it is detached from the DOM. This is useful for when you want to hide the content when the user scrolls away.`Default: true`                                                                                                                                                                                                                                                                   |
| `updatePositionStrategy`            | `enum`- 'optimized' \| 'always'                                                    | The strategy to use when updating the position of the content. When `'optimized'` the content will only be repositioned when the trigger is in the viewport. When `'always'` the content will be repositioned whenever the position changes.`Default: optimized`                                                                                                                                                                   |
| `strategy`                          | `enum`- 'fixed' \| 'absolute'                                                      | The positioning strategy to use for the floating element. When `'fixed'` the element will be positioned relative to the viewport. When `'absolute'` the element will be positioned relative to the nearest positioned ancestor.`Default: fixed`                                                                                                                                                                                    |
| `preventScroll`                     | `boolean`                                                                                                                                                                                                          | When `true`, prevents the body from scrolling when the content is open. This is useful when you want to use the content as a modal.`Default: true`                                                                                                                                                                                                                                                                                 |
| `customAnchor`                      | `union`- string \| HTMLElement \| Measurable \| null                               | Use an element other than the trigger to anchor the content to. If provided, the content will be anchored to the provided element instead of the trigger.`Default: null`                                                                                                                                                                                                                                                           |
| `onInteractOutside`                 | `function`- (event: PointerEvent) => void                                          | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default:  undefined`                                                                                                                                                                                                        |
| `onFocusOutside`                    | `function`- (event: FocusEvent) => void                                            | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default:  undefined`                                                                                                                                                                                                                                                  |
| `interactOutsideBehavior`           | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close`  |
| `onEscapeKeydown`                   | `function`- (event: KeyboardEvent) => void                                         | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default:  undefined`                                                                                                                                                                                                                    |
| `escapeKeydownBehavior`             | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` |
| `forceMount`                        | `boolean`                                                                                                                                                                                                          | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                                                                                                                                                                                                                                                                 |
| `dir`                               | `enum`- 'ltr' \| 'rtl'                                                             | The reading direction of the app.`Default: 'ltr'`                                                                                                                                                                                                                                                                                                                                                                                  |
| `ref` $bindable        | `HTMLDivElement`                                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                                                                                                                                                                         |
| `children`                          | `Snippet`- Snippet                                                                 | The children content to render.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                                                            |
| `child`                             | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };               | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                                                                                                                                                                  | | Data Attribute                             | Value                                                                                                      | Description                                                                                                |
| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum` | Whether the tooltip is open or closed.                                              |
| `data-tooltip-content`                            | `''`                                                                                              | Present on the tooltip content element. |

| CSS Variable                                                            | Description                                                                                                   |
| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--bits-tooltip-content-transform-origin` | The transform origin of the tooltip content element.                                   |
| `--bits-tooltip-content-available-width`                                       | The available width of the tooltip content element.                                    |
| `--bits-tooltip-content-available-height`                                      | The available height of the tooltip content element.                                   |
| `--bits-tooltip-anchor-width`                                                  | The width of the tooltip trigger element.                                              |
| `--bits-tooltip-anchor-height`                                                 | The height of the tooltip trigger element. |

### Tooltip.ContentStatic

The contents of the tooltip which are displayed when the tooltip is open. (Static/No Floating UI)

| Property                                                                           | Type                                                                                                                                                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onInteractOutside` | `function`- (event: PointerEvent) => void                                          | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default:  undefined`                                                                                                                                                                                                        |
| `onFocusOutside`                                 | `function`- (event: FocusEvent) => void                                            | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default:  undefined`                                                                                                                                                                                                                                                  |
| `interactOutsideBehavior`                        | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close`  |
| `onEscapeKeydown`                                | `function`- (event: KeyboardEvent) => void                                         | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default:  undefined`                                                                                                                                                                                                                    |
| `escapeKeydownBehavior`                          | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` |
| `forceMount`                                     | `boolean`                                                                                                                                                                                                          | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                                                                                                                                                                                                                                                                 |
| `dir`                                            | `enum`- 'ltr' \| 'rtl'                                                             | The reading direction of the app.`Default: 'ltr'`                                                                                                                                                                                                                                                                                                                                                                                  |
| `ref` $bindable                     | `HTMLDivElement`                                                                                                                                                                                                   | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                                                                                                                                                                                                                                                                         |
| `children`                                       | `Snippet`- Snippet                                                                 | The children content to render.`Default:  undefined`                                                                                                                                                                                                                                                                                                                                                                            |
| `child`                                          | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; };               | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                                                                                                                                                                                                                                  | | Data Attribute                             | Value                                                                                                      | Description                                                                                                |
| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum` | Whether the tooltip is open or closed.                                              |
| `data-tooltip-content`                            | `''`                                                                                              | Present on the tooltip content element. |

### Tooltip.Arrow

An optional arrow element which points to the trigger when the tooltip is open.

| Property                                                               | Type                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                     |
| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `width` | `number`                                                                                                                                                                                             | The width of the arrow in pixels.`Default: 8`                                                                                                                                     |
| `height`                             | `number`                                                                                                                                                                                             | The height of the arrow in pixels.`Default: 8`                                                                                                                                    |
| `ref` $bindable         | `HTMLDivElement`                                                                                                                                                                                     | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default:  undefined`                                                        |
| `children`                           | `Snippet`                                                                                                                                                                                            | The children content to render.`Default:  undefined`                                                                                                                           |
| `child`                              | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                             | Value         | Description                                                                                      |
| ----------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-arrow` | `''` | Present on the arrow element.                                             |
| `data-tooltip-arrow`                              | `''` | Present on the arrow element. |

----------------------------------------------------

# IsUsingKeyboard Documentation

A utility to track whether the user is actively using the keyboard or not.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

## Overview `IsUsingKeyboard` is a utility component that tracks whether the user is actively using the keyboard or not. This component is used internally by Bits UI components to provide keyboard accessibility features.

It provides global state that is shared across all instances of the class to prevent duplicate event listener registration.

## Usage

```svelte
<script lang="ts">
 import { IsUsingKeyboard } from "bits-ui";
 const isUsingKeyboard = new IsUsingKeyboard();
 const shouldShowMenu = $derived(isUsingKeyboard.current);
</script>
```

----------------------------------------------------

# mergeProps Documentation

A utility function to merge props objects.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

## Overview `mergeProps` is a utility function designed to merge multiple props objects. It's particularly useful for composing components with different prop sets or extending the functionality of existing components.

It is used internally by Bits UI components to merge the custom `restProps` you pass to a component with the props that Bits UI provides to the component.

## Key Features

- Merges multiple props objects  
- Chains event handlers with cancellation support  
- Combines class names  
- Merges style objects and strings  
- Chains non-event handler functions ## Detailed Behavior

### Event Handlers

Event handlers are chained in the order they're passed. If a handler calls `event.preventDefault()`, subsequent handlers in the chain are not executed.

```ts
const props1 = { onclick: (e: MouseEvent) => console.log("First click") };
const props2 = { onclick: (e: MouseEvent) => console.log("Second click") };
const mergedProps = mergeProps(props1, props2);
mergedProps.onclick(new MouseEvent("click")); // Logs: "First click" then "Second click"
```

If `preventDefault()` is called:

```ts
const props1 = { onclick: (e: MouseEvent) => console.log("First click") };
const props2 = {
 onclick: (e: MouseEvent) => {
  console.log("Second click");
  e.preventDefault();
 },
};
const props3 = { onclick: (e: MouseEvent) => console.log("Third click") };
const mergedProps = mergeProps(props1, props2, props3);
mergedProps.onclick(new MouseEvent("click")); // Logs: "First click" then "Second click" only
```

Since `props2` called `event.preventDefault()`, `props3`'s `onclick` handler will not be called.

### Non-Event Handler Functions

Non-event handler functions are also chained, but without the ability to prevent subsequent functions from executing:

```ts
const props1 = { doSomething: () => console.log("Action 1") };
const props2 = { doSomething: () => console.log("Action 2") };
const mergedProps = mergeProps(props1, props2);
mergedProps.doSomething(); // Logs: "Action 1" then "Action 2"
```

### Classes

Class names are merged using [`clsx`](https://www.npmjs.com/package/clsx):

```ts
const props1 = { class: "text-lg font-bold" };
const props2 = { class: ["bg-blue-500", "hover:bg-blue-600"] };
const mergedProps = mergeProps(props1, props2);
console.log(mergedProps.class); // "text-lg font-bold bg-blue-500 hover:bg-blue-600"
```

### Styles

Style objects and strings are merged, with later properties overriding earlier ones:

```ts
const props1 = { style: { color: "red", fontSize: "16px" } };
const props2 = { style: "background-color: blue; font-weight: bold;" };
const mergedProps = mergeProps(props1, props2);
console.log(mergedProps.style);
// "color: red; font-size: 16px; background-color: blue; font-weight: bold;"
```

```ts
import { mergeProps } from "bits-ui";
const props1 = { style: "--foo: red" };
const props2 = { style: { "--foo": "green", color: "blue" } };
const mergedProps = mergeProps(props1, props2);
console.log(mergedProps.style); // "--foo: green; color: blue;"
```

----------------------------------------------------

# Portal Documentation

A component that renders its children in a portal, preventing layout issues in complex UI structures.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

## Overview

The Portal component is a utility component that renders its children in a portal, preventing layout issues in complex UI structures. This component is used for the various Bits UI component that have a `Portal` sub-component.

## Usage

### Default behavior

By default, the `Portal` component will render its children in the `body` element.

```svelte
<script lang="ts">
 import { Portal } from "bits-ui";
</script>
<Portal>
 <div>This content will be portalled to the body</div>
</Portal>
```

### Custom target

You can use the `to` prop to specify a custom target element or selector to render the content to.

```svelte
<script lang="ts">
 import { Portal } from "bits-ui";
</script>
<div id="custom-target"></div>
<div>
 <Portal to="#custom-target">
  <div>This content will be portalled to the #custom-target element</div>
 </Portal>
</div>
```

### Disable

You can use the `disabled` prop to disable the portal behavior.

```svelte
<script lang="ts">
 import { Portal } from "bits-ui";
</script>
<Portal disabled>
 <div>This content will not be portalled</div>
</Portal>
```

----------------------------------------------------

# useId Documentation

A utility function to generate unique IDs.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

The `useId` function is a utility function that can be used to generate unique IDs. This function is used internally by all Bits UI components and is exposed for your convenience.

## Usage

```svelte
<script lang="ts">
 import { useId } from "bits-ui";
 const id = useId();
</script>
<label for={id}>Label here</label>
<input {id} />
```

----------------------------------------------------

# WithElementRef Documentation

A type helper to enable the `ref` prop on a component.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

The `WithElementRef` type helper is a convenience type that enables you to follow the same [`ref`](/docs/ref) prop pattern as used by Bits UI components when crafting your own.

```ts
type WithElementRef<T, U extends HTMLElement = HTMLElement> = T & { ref?: U | null };
```

This type helper is used internally by Bits UI components to enable the `ref` prop on a component.

## Usage Example

CustomButton.svelte

```svelte
<script lang="ts">
 import type { WithElementRef } from "bits-ui";
 type Props = WithElementRef<
  {
   yourPropA: string;
   yourPropB: number;
  },
  HTMLButtonElement
 >;
 let { yourPropA, yourPropB, ref = $bindable(null) }: Props = $props();
</script>
<button bind:this={ref}>
</button>
```

----------------------------------------------------

# WithoutChild Documentation

A type helper to exclude the child snippet prop from a component.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

The `WithoutChild` type helper is used to exclude the `child` snippet prop from a component. This is useful when you're building custom component wrappers that populate the `children` prop of a component and don't provide a way to pass a custom `child` snippet.

To learn more about the `child` snippet prop, check out the [delegation](/docs/child-snippet) documentation.

CustomAccordionHeader.svelte

```svelte
<script lang="ts">
 import { Accordion, type WithoutChild } from "bits-ui";
 let { children, ...restProps }: WithoutChild<Accordion.ItemProps> = $props();
</script>
<Accordion.Header {...restProps}>
 <Accordion.Trigger>
  {@render children?.()}
 </Accordion.Trigger>
</Accordion.Header>
```

----------------------------------------------------

# WithoutChildrenOrChild Documentation

A type helper to exclude the child ad children snippet props from a component.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

The `WithoutChildrenOrChild` type helper is used to exclude the `child` and `children` props from a component. This is useful when you're building custom component wrappers that populate the `children` prop of a component and don't provide a way to pass a custom `children` or `child` snippet.

To learn more about the `child` snippet prop, check out the [delegation](/docs/child-snippet) documentation.

CustomAccordionTrigger.svelte

```svelte
<script lang="ts">
 import { Accordion, type WithoutChildrenOrChild } from "bits-ui";
 let {
  title,
  ...restProps
 }: WithoutChildrenOrChild<
  Accordion.TriggerProps & {
   title: string;
  }
 > = $props();
</script>
<Accordion.Trigger>
 {title}
</Accordion.Trigger>
```

Now, the `CustomAccordionTrigger` component won't expose `children` or `child` props to the user, but will expose the other root component props.

----------------------------------------------------

# WithoutChildren Documentation

A type helper to exclude the children snippet prop from a component.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

The `WithoutChildren` type helper is used to exclude the `children` snippet prop from a component. This is useful when you're building custom component wrappers that populate the `children` prop of a component.

CustomAccordion.svelte

```svelte
<script lang="ts">
 import { Accordion, type WithoutChildren } from "bits-ui";
 let { value, onValueChange, ...restProps }: WithoutChildren<Accordion.RootProps> = $props();
</script>
<Accordion.Root {...restProps}>
 <Accordion.Item {value} {onValueChange}>
  <Accordion.Header />
  <Accordion.Trigger />
  <Accordion.Content />
 </Accordion.Item>
</Accordion.Root>
```

In the example above, we're using the `WithoutChildren` type helper to exclude the `children` snippet prop from the `Accordion.Root` component. This ensures our exposed props are consistent with what is being used internally.

----------------------------------------------------