--- url: /docs/overview/accessibility.md description: >- Reka UI follow the WAI-ARIA authoring practices guidelines and are tested in a wide selection of modern browsers and commonly used assistive technologies. --- # Accessibility We take care of many of the difficult implementation details related to accessibility, including `aria` and `role` attributes, focus management, and keyboard navigation. That means that users should be able to use our components as-is in most contexts and rely on functionality to follow the expected accessibility design patterns. ## WAI-ARIA [WAI-ARIA](https://www.w3.org/TR/wai-aria-1.2/), published and maintained by the W3C, specifies the semantics for many common UI patterns that show up in Reka UI. This is designed to provide meaning for controls that aren't built using elements provided by the browser. For example, if you use a `div` instead of a `button` element to create a button, there are attributes you need to add to the `div` in order to convey that it's a button for screen readers or voice recognition tools. In addition to semantics, there are behaviors that are expected from different types of components. A `button` element is going to respond to certain interactions in ways that a `div` will not, so it's up to the developer to reimplement those interactions with JavaScript. The [WAI-ARIA authoring practices](https://www.w3.org/TR/wai-aria-practices-1.2/) provide additional guidance for implementing behaviors for various controls that come with Reka UI. ## Accessible Labels With many built-in form controls, the native HTML `label` element is designed to provide semantic meaning and context for corresponding `input` elements. For non-form control elements, or for custom controls like those provided by Reka UI, [WAI-ARIA provides a specification](https://www.w3.org/TR/wai-aria-1.2/#namecalculation) for how to provide accessible names and descriptions to those controls. Where possible, Reka UI include abstractions to make labelling our controls simple. The [`Label`](../components/label) primitive is designed to work with many of our controls. Ultimately it's up to you to provide those labels so that users have the proper context when navigating your application. ## Keyboard Navigation Many complex components, like [`Tabs`](../components/tabs) and [`Dialog`](../components/dialog), come with expectations from users on how to interact with their content using a keyboard or other non-mouse input modalities. Reka UI provide basic keyboard support in accordance with the [WAI-ARIA authoring practices](https://www.w3.org/TR/wai-aria-practices-1.2/). ## Focus Management Proper keyboard navigation and good labelling often go hand-in-hand with managing focus. When a user interacts with an element and something changes as a result, it's often helpful to move focus with the interaction so that the next tab stop is logical depending on the new context of the app. And for screen reader users, moving focus often results in an announcement to convey this new context, which relies on proper labelling. In many Reka UI, we move focus based on the interactions a user normally takes in a given component. For example, in [`AlertDialog`](../components/alert-dialog), when the modal is opened, focus is programmatically moved to a `Cancel` button element to anticipate a response to the prompt. --- --- url: /docs/components/accordion.md description: >- A vertically stacked set of interactive headings that each reveal an associated section of content. --- # Accordion ## Features ## Installation Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Root Contains all the parts of an Accordion **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `collapsible` | When type is "single", allows closing content when clicking trigger for an open item. When type is "multiple", this prop has no effect. | `boolean` | No | `false` | | `defaultValue` | The default active value of the item(s). Use when you do not need to control the state of the item(s). | `T` | No | - | | `dir` | The reading direction of the accordion when applicable. If omitted, assumes LTR (left-to-right) reading mode. | `"ltr" \| "rtl"` | No | - | | `disabled` | When true, prevents the user from interacting with the accordion and all its items | `boolean` | No | `false` | | `modelValue` | The controlled value of the active item(s). Use this when you need to control the state of the items. Can be binded with v-model | `T` | No | - | | `orientation` | The orientation of the accordion. | `"vertical" \| "horizontal"` | No | `"vertical"` | | `type` | Determines whether a "single" or "multiple" items can be selected at a time. This prop will overwrite the inferred type from modelValue and defaultValue. | `"single" \| "multiple"` | No | - | | `unmountOnHide` | When true, the element will be unmounted on closed state. | `boolean` | No | `true` | **Events** | Name | Description | Type | | --- | --- | --- | | `update:modelValue` | Event handler called when the expanded state of an item changes | `[value: (ExplicitType extends "single" ? string : string[])]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `modelValue` | Current active value | `AcceptableValue \| AcceptableValue[] \| undefined` | ### Item Contains all the parts of a collapsible section. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | Whether or not an accordion item is disabled from user interaction. When true, prevents the user from interacting with the item. | `boolean` | No | - | | `unmountOnHide` | When true, the element will be unmounted on closed state. | `boolean` | No | - | | `value` | A string value for the accordion item. All items within an accordion should use a unique value. | `string` | Yes | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `open` | Current open state | `boolean` | ### Header Wraps an `AccordionTrigger`. Use the `asChild` prop to update it to the appropriate heading level for your page. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"h3"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Trigger Toggles the collapsed state of its associated item. It should be nested inside of an `AccordionHeader`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Content Contains the collapsible content for an item. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | ## Examples ### Expanded by default Use the `defaultValue` prop to define the open item by default. ```vue line=4 ``` ### Allow collapsing all items Use the `collapsible` prop to allow all items to close. ```vue line=4 ``` ### Multiple items open at the same time Set the `type` prop to `multiple` to enable opening multiple items at once. ```vue line=2 ``` ### Rotated icon when open You can add extra decorative elements, such as chevrons, and rotate it when the item is open. ```vue line=16 // index.vue ``` ```css line=5-7 /* styles.css */ .AccordionChevron { transition: transform 300ms; } .AccordionTrigger[data-state="open"] > .AccordionChevron { transform: rotate(180deg); } ``` ### Horizontal orientation Use the `orientation` prop to create a horizontal Accordion ```vue line=2 ``` ### Animating content size Use the `--reka-accordion-content-width` and/or `--reka-accordion-content-height` CSS variables to animate the size of the content when it opens/closes: ```vue line=11 // index.vue ``` ```css line=17,23 /* styles.css */ .AccordionContent { overflow: hidden; } .AccordionContent[data-state="open"] { animation: slideDown 300ms ease-out; } .AccordionContent[data-state="closed"] { animation: slideUp 300ms ease-out; } @keyframes slideDown { from { height: 0; } to { height: var(--reka-accordion-content-height); } } @keyframes slideUp { from { height: var(--reka-accordion-content-height); } to { height: 0; } } ``` ### Render content even when closed By default hidden content will be removed, use `:unmountOnHide="false"` to keep the content always available. This will also allow browser to search the hidden text, and open the accordion. ```vue line=2 ``` ## Accessibility Adheres to the [Accordion WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion). ### Keyboard Interactions --- --- url: /docs/components/alert-dialog.md description: >- A modal dialog that interrupts the user with important content and expects a response. --- # Alert Dialog ## Features ## Installation Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Root Contains all the parts of an alert dialog. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `defaultOpen` | The open state of the dialog when it is initially rendered. Use when you do not need to control its open state. | `boolean` | No | - | | `open` | The controlled open state of the dialog. Can be binded as v-model:open. | `boolean` | No | - | | `unmountOnHide` | When set to false, the dialog content will not be unmounted when closed, but instead hidden with CSS. Useful for SEO or when you want to improve performance by not remounting the component on every open. | `boolean` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `update:open` | Event handler called when the open state of the dialog changes. | `[value: boolean]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `open` | Current open state | `boolean` | | `close` | Close the dialog | `(): void` | ### Trigger A button that opens the dialog. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Portal When used, portals your overlay and content parts into the body. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `defer` | Defer the resolving of a Teleport target until other parts of the application have mounted (requires Vue 3.5.0+) reference | `boolean` | No | - | | `disabled` | Disable teleport and render the component inline reference | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | | `to` | Vue native teleport component prop :to reference | `string \| HTMLElement` | No | - | ### Overlay A layer that covers the inert portion of the view when the dialog is open. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | ### Content Contains content to be rendered when the dialog is open. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disableOutsidePointerEvents` | When true, hover/focus/click interactions will be disabled on elements outside the DismissableLayer. Users will need to click twice on outside elements to interact with them: once to close the DismissableLayer, and again to trigger the element. | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `closeAutoFocus` | Event handler called when auto-focusing on close. Can be prevented. | `[event: Event]` | | `escapeKeyDown` | Event handler called when the escape key is down. Can be prevented. | `[event: KeyboardEvent]` | | `focusOutside` | Event handler called when the focus moves outside of the DismissableLayer. Can be prevented. | `[event: FocusOutsideEvent]` | | `interactOutside` | Event handler called when an interaction happens outside the DismissableLayer. Specifically, when a pointerdown event happens outside or focus moves outside of it. Can be prevented. | `[event: PointerDownOutsideEvent \| FocusOutsideEvent]` | | `openAutoFocus` | Event handler called when auto-focusing on open. Can be prevented. | `[event: Event]` | | `pointerDownOutside` | Event handler called when a pointerdown event happens outside of the DismissableLayer. Can be prevented. | `[event: PointerDownOutsideEvent]` | ### Cancel A button that closes the dialog. This button should be distinguished visually from `AlertDialogAction` buttons. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Action A button that closes the dialog. These buttons should be distinguished visually from the `AlertDialogCancel` button. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Title An accessible name to be announced when the dialog is opened. Alternatively, you can provide `aria-label` or `aria-labelledby` to `AlertDialogContent` and exclude this component. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"h2"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Description An accessible description to be announced when the dialog is opened. Alternatively, you can provide `aria-describedby` to `AlertDialogContent` and exclude this component. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"p"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ## Examples ### Close after asynchronous form submission Use the controlled props to programmatically close the Alert Dialog after an async operation has completed. ```vue line=14,15,19,25-29 ``` ### Custom portal container Customise the element that your alert dialog portals into. ```vue line=4,17 ``` ## Accessibility Adheres to the [Alert and Message Dialogs WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog). ### Keyboard Interactions --- --- url: /docs/guides/animation.md description: >- Animate Reka UI with CSS keyframes, native Vue Transition or JavaScript animation library of your choice. --- # Animation Adding animation to Reka UI should feel similar to any other component, but there are some caveats noted here in regards to exiting animations with JS animation libraries. ## Animating with CSS animation The simplest way to animate Primitives is with CSS. You can use CSS animation to animate both mount and unmount phases. The latter is possible because the Reka UI will suspend unmount while your animation plays out. ```css @keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } } @keyframes fadeOut { from { opacity: 1; } to { opacity: 0; } } .DialogOverlay[data-state="open"], .DialogContent[data-state="open"] { animation: fadeIn 300ms ease-out; } .DialogOverlay[data-state="closed"], .DialogContent[data-state="closed"] { animation: fadeOut 300ms ease-in; } ``` ## Animating with Vue Transition Other than using CSS animation, you might prefer to use the native Vue ``. Great news! It should be as easy as wrapping component (that has `forceMount` prop), and you are done! ```vue line=11,13,14,19,25-33 ``` ## ⭐️ Animating with Motion Vue [Motion Vue](https://motion.dev/docs/vue) is the recommended animation library for Reka UI. This lightweight, powerful library integrates seamlessly with components and offers extensive flexibility for creating smooth, performant animations. ```vue line=3,12,14-18,22-26,29,31 ``` Check out this [Stackblitz Demo](https://stackblitz.com/edit/x7y44ngl?file=src%2FApp.vue) 🤩 ## Delegating unmounting for JavaScript Animation When many stateful Primitives are hidden from view, they are actually removed from the DOM. JavaScript animation libraries need control of the unmounting phase, so we provide the `forceMount` prop on many components to allow consumers to delegate the mounting and unmounting of children based on the animation state determined by those libraries. For example, if you want to use [@vueuse/motion](https://motion.vueuse.org/) to animate a `Dialog`, you would do so by conditionally rendering the dialog `Overlay` and `Content` parts based on the animation state from one of its composable like `useSpring`: ```vue line=32,34,41 ``` Check out this [Stackblitz Demo](https://stackblitz.com/edit/macsaz-xuwbw3im?file=src%2FApp.vue) --- --- url: /docs/components/aspect-ratio.md description: Displays content within a desired ratio. --- # Aspect Ratio ## Features ## Installation Install the component from your command line. ## Anatomy Import the component. ```vue ``` ## API Reference ### Root Contains the content you want to constrain to a given ratio. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `ratio` | The desired ratio. Eg: 16/9 | `number` | No | `1` | **Slots** | Name | Description | Type | | --- | --- | --- | | `aspect` | Current aspect ratio (in %) | `number` | --- --- url: /docs/components/autocomplete.md description: >- An input with suggestions that allows free-form text entry. Unlike Combobox, the value is the input text itself rather than a selected item. --- # Autocomplete Alpha ## Features ## Installation Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## Autocomplete vs. Combobox The Autocomplete component is similar to the [Combobox](/docs/components/combobox) but with a key difference: | | Autocomplete | Combobox | | --- | --- | --- | | **`modelValue`** | The input text (`string`) | The selected item (`AcceptableValue`) | | **Free-form text** | Yes — any text is valid | No — must select from the list | | **`multiple`** | Not supported | Supported | | **Input on blur** | Retains typed text by default | Resets to selected value by default | | **Item selection** | Fills the input with the item's text value | Sets `modelValue` to the item's value | Use **Autocomplete** when the user should be able to type anything with optional suggestions. Use **Combobox** when the user must pick from a predefined set of options. ## API Reference ### Root Contains all the parts of an Autocomplete. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `defaultOpen` | The open state of the autocomplete when it is initially rendered. Use when you do not need to control its open state. | `boolean` | No | - | | `defaultValue` | The value of the autocomplete when initially rendered. Use when you do not need to control the state. | `string` | No | - | | `dir` | The reading direction of the autocomplete when applicable. | `"ltr" \| "rtl"` | No | - | | `disabled` | When true, prevents the user from interacting with autocomplete | `boolean` | No | - | | `highlightOnHover` | When true, hover over item will trigger highlight | `boolean` | No | `true` | | `ignoreFilter` | When true, disable the default filters | `boolean` | No | - | | `modelValue` | The controlled value of the Autocomplete (the input text). Can be bound with v-model. | `string` | No | - | | `name` | The name of the field. Submitted with its owning form as part of a name/value pair. | `string` | No | - | | `open` | The controlled open state of the Autocomplete. Can be bound with v-model:open. | `boolean` | No | - | | `openOnClick` | Whether to open the autocomplete when the input is clicked | `boolean` | No | `false` | | `openOnFocus` | Whether to open the autocomplete when the input is focused | `boolean` | No | `false` | | `required` | When true, indicates that the user must set the value before the owning form can be submitted. | `boolean` | No | - | | `resetSearchTermOnBlur` | Whether to reset the searchTerm when the Autocomplete input blurred | `boolean` | No | `false` | **Events** | Name | Description | Type | | --- | --- | --- | | `highlight` | Event handler when highlighted element changes. | `[payload: { ref: HTMLElement; value: string; }]` | | `update:modelValue` | Event handler called when the value changes. | `[value: string]` | | `update:open` | Event handler called when the open state of the autocomplete changes. | `[value: boolean]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `open` | Current open state | `boolean` | | `modelValue` | Current active value | `string` | ### Anchor Used as an anchor if you set `AutocompleteContent`'s position to `popper`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `reference` | The reference (or anchor) element that is being referred to for positioning. If not provided will use the current component as anchor. | `ReferenceElement` | No | - | ### Input The input component to search through the autocomplete items. Typing updates the `modelValue` directly. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"input"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `autoFocus` | Focus on element when mounted. | `boolean` | No | - | | `disabled` | When true, prevents the user from interacting with item | `boolean` | No | - | | `modelValue` | The controlled value of the filter. Can be binded with v-model. | `string` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `update:modelValue` | Event handler called when the value changes. | `[string]` | ### Trigger The button that toggles the Autocomplete Content. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | When true, prevents the user from interacting with item | `boolean` | No | - | ### Cancel The button that clears the input text and resets the value. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Empty Shown when none of the items match the query. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Portal When used, portals the content part into the `body`. You need to set `position="popper"` for `AutocompleteContent` to make sure the position was automatically computed similar to `Popover` or `DropdownMenu`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `defer` | Defer the resolving of a Teleport target until other parts of the application have mounted (requires Vue 3.5.0+) reference | `boolean` | No | - | | `disabled` | Disable teleport and render the component inline reference | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | | `to` | Vue native teleport component prop :to reference | `string \| HTMLElement` | No | - | ### Content The component that pops out when the autocomplete is open. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `align` | The preferred alignment against the trigger. May change when collisions occur. | `"start" \| "center" \| "end"` | No | - | | `alignFlip` | Flip alignment when colliding with boundary. May only occur when prioritizePosition is true. | `boolean` | No | - | | `alignOffset` | An offset in pixels from the start or end alignment options. | `number` | No | - | | `arrowPadding` | The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners. | `number` | No | - | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `avoidCollisions` | When true, overrides the side and align preferences to prevent collisions with boundary edges. | `boolean` | No | - | | `bodyLock` | The document.body will be lock, and scrolling will be disabled. | `boolean` | No | - | | `collisionBoundary` | The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. | `Element \| (Element \| null)[] \| null` | No | - | | `collisionPadding` | The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }. | `number \| Partial>` | No | - | | `dir` | The reading direction of the popper content when applicable. If omitted, inherits globally from ConfigProvider or assumes LTR (left-to-right) reading mode. | `"ltr" \| "rtl"` | No | - | | `disableOutsidePointerEvents` | When true, hover/focus/click interactions will be disabled on elements outside the DismissableLayer. Users will need to click twice on outside elements to interact with them: once to close the DismissableLayer, and again to trigger the element. | `boolean` | No | - | | `disableUpdateOnLayoutShift` | Whether to disable the update position for the content when the layout shifted. | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | | `hideShiftedArrow` | When true, hides the arrow when it cannot be centered to the reference element. | `boolean` | No | - | | `hideWhenDetached` | Whether to hide the content when the trigger becomes fully occluded. | `boolean` | No | - | | `hideWhenEmpty` | When true, hides the content when there are no items matching the filter. | `boolean` | No | - | | `memoDependencies` | Reactive dependencies that should invalidate the memoized content subtree. | `unknown[]` | No | - | | `position` | The positioning mode to use, inline is the default and you can control the position using CSS. popper positions content in the same way as our other primitives, for example Popover or DropdownMenu. | `"inline" \| "popper"` | No | - | | `positionStrategy` | The type of CSS position property to use. | `"fixed" \| "absolute"` | No | - | | `prioritizePosition` | Force content to be position within the viewport. Might overlap the reference element, which may not be desired. | `boolean` | No | - | | `reference` | The custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element. | `ReferenceElement` | No | - | | `side` | The preferred side of the trigger to render against when open. Will be reversed when collisions occur and avoidCollisions is enabled. | `"top" \| "right" \| "bottom" \| "left"` | No | - | | `sideFlip` | Flip to the opposite side when colliding with boundary. | `boolean` | No | - | | `sideOffset` | The distance in pixels from the trigger. | `number` | No | - | | `sticky` | 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. | `"partial" \| "always"` | No | - | | `updatePositionStrategy` | Strategy to update the position of the floating element on every animation frame. | `"always" \| "optimized"` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `escapeKeyDown` | Event handler called when the escape key is down. Can be prevented. | `[event: KeyboardEvent]` | | `focusOutside` | Event handler called when the focus moves outside of the DismissableLayer. Can be prevented. | `[event: FocusOutsideEvent]` | | `interactOutside` | Event handler called when an interaction happens outside the DismissableLayer. Specifically, when a pointerdown event happens outside or focus moves outside of it. Can be prevented. | `[event: PointerDownOutsideEvent \| FocusOutsideEvent]` | | `pointerDownOutside` | Event handler called when a pointerdown event happens outside of the DismissableLayer. Can be prevented. | `[event: PointerDownOutsideEvent]` | ### Viewport The scrolling viewport that contains all of the items. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `nonce` | Will add nonce attribute to the style tag which can be used by Content Security Policy. If omitted, inherits globally from ConfigProvider. | `string` | No | - | ### Item The component that contains the autocomplete items. When selected, the item's string value fills the input. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | When true, prevents the user from interacting with the item. | `boolean` | No | - | | `textValue` | A string representation of the item contents. If the children are not plain text, then the textValue prop must also be set to a plain text representation, which will be used for autocomplete in the ComboBox. | `string` | No | - | | `value` | The value given as data when submitted with a name. | `T` | Yes | - | **Events** | Name | Description | Type | | --- | --- | --- | | `select` | Event handler called when the selecting item. It can be prevented by calling event.preventDefault. | `[event: SelectEvent]` | ### Group Used to group multiple items. Use in conjunction with `AutocompleteLabel` to ensure good accessibility via automatic labelling. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Label Used to render the label of a group. It won't be focusable using arrow keys. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `for` | | `string` | No | - | ### Separator Used to visually separate items in the Autocomplete. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Arrow An optional arrow element to render alongside the content. This can be used to help visually link the trigger with the `AutocompleteContent`. Must be rendered inside `AutocompleteContent`. Only available when `position` is set to `popper`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"svg"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `height` | The height of the arrow in pixels. | `number` | No | `5` | | `rounded` | When true, render the rounded version of arrow. Do not work with as/asChild | `boolean` | No | - | | `width` | The width of the arrow in pixels. | `number` | No | `10` | ### Virtualizer Virtual container to achieve list virtualization. See the [virtualization guide](../guides/virtualization.md) for more general info on virtualization. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `estimateSize` | Estimated size (in px) of each item | `number \| ((index: number) => number)` | No | - | | `options` | List of items | `T` | Yes | - | | `overscan` | Number of items rendered outside the visible area | `number` | No | - | | `textContent` | Text content for each item to achieve type-ahead feature | `((option: T) => string)` | No | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `option` | | `T` | | `virtualizer` | | `Virtualizer` | | `virtualItem` | | `VirtualItem` | ## Examples ### Basic usage The `modelValue` is a string that reflects whatever the user types. Selecting an item fills the input with that item's text. ```vue ``` ### Hide menu when empty Use the `hideWhenEmpty` prop on `AutocompleteContent` to hide the menu when no items match the filter. ```vue ``` ### With form submission The Autocomplete value is submitted as a regular text field in forms. ```vue ``` ## Accessibility Adheres to the [Combobox WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox). ### Keyboard Interactions --- --- url: /docs/components/avatar.md description: An image element with a fallback for representing the user. --- # Avatar ## Features ## Installation Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Root Contains all the parts of an avatar **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"span"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Image The image to render. By default it will only render when it has loaded. You can use the `@loadingStatusChange` handler if you need more control. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"img"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `crossOrigin` | | `"" \| "anonymous" \| "use-credentials"` | No | - | | `referrerPolicy` | | `"" \| "no-referrer" \| "no-referrer-when-downgrade" \| "origin" \| "origin-when-cross-origin" \| "same-origin" \| "strict-origin" \| "strict-origin-when-cross-origin" \| "unsafe-url"` | No | - | | `src` | | `string` | Yes | - | **Events** | Name | Description | Type | | --- | --- | --- | | `loadingStatusChange` | A callback providing information about the loading status of the image. This is useful in case you want to control more precisely what to render as the image is loading. | `[value: ImageLoadingStatus]` | ### Fallback An element that renders when the image hasn't loaded. This means whilst it's loading, or if there was an error. If you notice a flash during loading, you can provide a `delayMs` prop to delay its rendering so it only renders for those with slower connections. For more control, use the `@loadingStatusChange` emit on `AvatarImage`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"span"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `delayMs` | Useful for delaying rendering so it only appears for those with slower connections. | `number` | No | - | ## Examples ### Clickable Avatar with tooltip You can compose the Avatar with a [Tooltip](/docs/components/tooltip) to display extra information. ```vue line=6-7,9,11-15 ``` --- --- url: /docs/components/calendar.md description: 'Displays dates and days of the week, facilitating date-related interactions.' --- # Calendar Alpha ## Features ## Preface The component depends on the [@internationalized/date](https://react-spectrum.adobe.com/internationalized/date/index.html) package, which solves a lot of the problems that come with working with dates and times in JavaScript. We highly recommend reading through the documentation for the package to get a solid feel for how it works, and you'll need to install it in your project to use the date-related components. ## Installation Install the date package. Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Root Contains all the parts of a calendar **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `calendarLabel` | The accessible label for the calendar | `string` | No | - | | `defaultPlaceholder` | The default placeholder date | `DateValue` | No | - | | `defaultValue` | The default value for the calendar | `DateValue` | No | - | | `dir` | The reading direction of the calendar when applicable. If omitted, inherits globally from ConfigProvider or assumes LTR (left-to-right) reading mode. | `"ltr" \| "rtl"` | No | - | | `disabled` | Whether the calendar is disabled | `boolean` | No | `false` | | `disableDaysOutsideCurrentView` | Whether or not to disable days outside the current view. | `boolean` | No | `false` | | `fixedWeeks` | Whether or not to always display 6 weeks in the calendar | `boolean` | No | `false` | | `initialFocus` | If true, the calendar will focus the selected day, today, or the first day of the month depending on what is visible when the calendar is mounted | `boolean` | No | `false` | | `isDateDisabled` | A function that returns whether or not a date is disabled | `Matcher` | No | - | | `isDateUnavailable` | A function that returns whether or not a date is unavailable | `Matcher` | No | - | | `locale` | The locale to use for formatting dates | `string` | No | - | | `maxValue` | The maximum date that can be selected | `DateValue` | No | - | | `minValue` | The minimum date that can be selected | `DateValue` | No | - | | `modelValue` | The controlled selected date value of the calendar. Can be bound as v-model. | `DateValue \| DateValue[] \| null` | No | - | | `multiple` | Whether multiple dates can be selected | `boolean` | No | `false` | | `nextPage` | A function that returns the next page of the calendar. It receives the current placeholder as an argument inside the component. | `((placeholder: DateValue) => DateValue)` | No | - | | `numberOfMonths` | The number of months to display at once | `number` | No | `1` | | `pagedNavigation` | This property causes the previous and next buttons to navigate by the number of months displayed at once, rather than one month | `boolean` | No | `false` | | `placeholder` | The placeholder date, which is used to determine what month to display when no date is selected | `DateValue` | No | - | | `preventDeselect` | Whether or not to prevent the user from deselecting a date without selecting another date first | `boolean` | No | `false` | | `prevPage` | A function that returns the previous page of the calendar. It receives the current placeholder as an argument inside the component. | `((placeholder: DateValue) => DateValue)` | No | - | | `readonly` | Whether the calendar is readonly | `boolean` | No | `false` | | `weekdayFormat` | The format to use for the weekday strings provided via the weekdays slot prop | `"narrow" \| "short" \| "long"` | No | `"narrow"` | | `weekStartsOn` | The day of the week to start the calendar on | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `update:modelValue` | Event handler called whenever the model value changes | `[date: DateValue]` | | `update:placeholder` | Event handler called whenever the placeholder value changes | `[date: DateValue]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `date` | The current date of the placeholder | `DateValue` | | `grid` | The grid of dates | `Grid[]` | | `weekDays` | The days of the week | `string[]` | | `weekStartsOn` | The start of the week | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | | `locale` | The calendar locale | `string` | | `fixedWeeks` | Whether or not to always display 6 weeks in the calendar | `boolean` | | `modelValue` | The current date of the calendar | `DateValue \| DateValue[] \| undefined` | ### Header Contains the navigation buttons and the heading segments. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Prev Button Calendar navigation button. It navigates the calendar one month/year/decade in the past based on the current calendar view. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `prevPage` | The function to be used for the prev page. Overwrites the prevPage function set on the CalendarRoot. | `((placeholder: DateValue) => DateValue)` | No | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `disabled` | Current disable state | `boolean` | ### Next Button Calendar navigation button. It navigates the calendar one month/year/decade in the future based on the current calendar view. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `nextPage` | The function to be used for the next page. Overwrites the nextPage function set on the CalendarRoot. | `((placeholder: DateValue) => DateValue)` | No | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `disabled` | Current disable state | `boolean` | ### Heading Heading for displaying the current month and year **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `headingValue` | Current month and year | `string` | ### Grid Container for wrapping the calendar grid. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"table"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Grid Head Container for wrapping the grid head. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"thead"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Grid Body Container for wrapping the grid body. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"tbody"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Grid Row Container for wrapping the grid row. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"tr"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Head Cell Container for wrapping the head cell. Used for displaying the week days. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"th"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Cell Container for wrapping the calendar cells. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"td"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `date` | The date value for the cell | `DateValue` | Yes | - | ### Cell Trigger Interactable container for displaying the cell dates. Clicking it selects the date. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `day` | The date value provided to the cell trigger | `DateValue` | Yes | - | | `month` | The month in which the cell is rendered | `DateValue` | Yes | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `dayValue` | Current day | `string` | | `disabled` | Current disable state | `boolean` | | `selected` | Current selected state | `boolean` | | `today` | Current today state | `boolean` | | `outsideView` | Current outside view state | `boolean` | | `outsideVisibleView` | Current outside visible view state | `boolean` | | `unavailable` | Current unavailable state | `boolean` | ## Examples ### Calendar with Year Incrementation This example showcases a calendar which allows incrementing the year. ### Calendar with Locale and Calendar System Selection This example showcases some of the available locales and how the calendar systems are displayed. ### Calendar swipe gesture navigation This component demonstrates intuitive calendar navigation using touch-based swipe gestures, user-friendly way to browse through months. ### Calendar week numbers This example showcases usage of the CalendarWeek component used to display the number of the week. ## Accessibility ### Keyboard Interactions --- --- url: /docs/components/checkbox.md description: A control that allows the user to toggle between checked and not checked. --- # Checkbox ## Features ## Installation Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Root Contains all the parts of a checkbox. An `input` will also render when used within a `form` to ensure events propagate correctly. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `defaultValue` | The value of the checkbox when it is initially rendered. Use when you do not need to control its value. | `T \| "indeterminate"` | No | - | | `disabled` | When true, prevents the user from interacting with the checkbox | `boolean` | No | - | | `falseValue` | The value used when the checkbox is unchecked. Defaults to false. | `T` | No | `(() => false) as unknown as undefined` | | `id` | Id of the element | `string` | No | - | | `modelValue` | The controlled value of the checkbox. Can be binded with v-model. | `null \| T \| "indeterminate"` | No | - | | `name` | The name of the field. Submitted with its owning form as part of a name/value pair. | `string` | No | - | | `required` | When true, indicates that the user must set the value before the owning form can be submitted. | `boolean` | No | - | | `trueValue` | The value used when the checkbox is checked. Defaults to true. | `T` | No | `(() => true) as unknown as undefined` | | `value` | The value given as data when submitted with a name. | `AcceptableValue` | No | `"on"` | **Events** | Name | Description | Type | | --- | --- | --- | | `update:modelValue` | Event handler called when the value of the checkbox changes. | `[value: T \| "indeterminate"]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `modelValue` | Current value | `T \| "indeterminate"` | | `state` | Current state | `false \| true \| "indeterminate"` | ### Indicator Renders when the checkbox is in a checked or indeterminate state. You can style this element directly, or you can use it as a wrapper to put an icon into, or both. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"span"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | ### Group Root Wrapper around `CheckboxRoot` to support array of `modelValue` **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `defaultValue` | The value of the checkbox when it is initially rendered. Use when you do not need to control its value. | `T[]` | No | - | | `dir` | The direction of navigation between items. | `"ltr" \| "rtl"` | No | - | | `disabled` | When true, prevents the user from interacting with the checkboxes | `boolean` | No | - | | `loop` | Whether keyboard navigation should loop around | `boolean` | No | - | | `modelValue` | The controlled value of the checkbox. Can be binded with v-model. | `T[]` | No | - | | `name` | The name of the field. Submitted with its owning form as part of a name/value pair. | `string` | No | - | | `orientation` | The orientation of the group. Mainly so arrow navigation is done accordingly (left & right vs. up & down) | `"vertical" \| "horizontal"` | No | - | | `required` | When true, indicates that the user must set the value before the owning form can be submitted. | `boolean` | No | - | | `rovingFocus` | When false, navigating through the items using arrow keys will be disabled. | `boolean` | No | `true` | **Events** | Name | Description | Type | | --- | --- | --- | | `update:modelValue` | Event handler called when the value of the checkbox changes. | `[value: T[]]` | ## Examples ### Custom Values Use the `trueValue` and `falseValue` props to specify custom values for the checked and unchecked states instead of the default `true`/`false`. ```vue line=5-6,11-12 ``` ### Indeterminate You can set the checkbox to `indeterminate` by taking control of its state. ```vue line=5,9-14,16-18 ``` ## Accessibility Adheres to the [tri-state Checkbox WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox). ### Keyboard Interactions --- --- url: /docs/components/collapsible.md description: An interactive component which expands/collapses a panel. --- # Collapsible ## Features ## Installation Install the component from your command line. ## Anatomy Import the components and piece the parts together. ```vue ``` ## API Reference ### Root Contains all the parts of a collapsible **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `defaultOpen` | The open state of the collapsible when it is initially rendered. Use when you do not need to control its open state. | `boolean` | No | `false` | | `disabled` | When true, prevents the user from interacting with the collapsible. | `boolean` | No | - | | `open` | The controlled open state of the collapsible. Can be binded with v-model. | `boolean` | No | - | | `unmountOnHide` | When true, the element will be unmounted on closed state. | `boolean` | No | `true` | **Events** | Name | Description | Type | | --- | --- | --- | | `update:open` | Event handler called when the open state of the collapsible changes. | `[value: boolean]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `open` | Current open state | `boolean` | ### Trigger The button that toggles the collapsible **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Content The component that contains the collapsible content. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `contentFound` | | `[(void)?]` | ## Examples ### Animating content size Use the `--reka-collapsible-content-width` and/or `--reka-collapsible-content-height` CSS variables to animate the size of the content when it opens/closes. Here's a demo: ```vue line=10 // index.vue ``` ```css line=17,23 /* styles.css */ .CollapsibleContent { overflow: hidden; } .CollapsibleContent[data-state="open"] { animation: slideDown 300ms ease-out; } .CollapsibleContent[data-state="closed"] { animation: slideUp 300ms ease-out; } @keyframes slideDown { from { height: 0; } to { height: var(--reka-collapsible-content-height); } } @keyframes slideUp { from { height: var(--reka-collapsible-content-height); } to { height: 0; } } ``` ### Render content even when collapsed By default hidden content will be removed, use `:unmountOnHide="false"` to keep the content always available. This will also allow browser to search the hidden text, and open the collapsible. ```vue line=6 ``` ## Accessibility Adheres to the [Disclosure WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure). ### Keyboard Interactions --- --- url: /docs/components/color-area.md description: A two-dimensional area for selecting color values in a specific color space. --- # Color Area Alpha ## Features ## Installation Install the component from your command line. Looking for a complete color picker? Check out the [Color Picker example](/examples/color-picker) that combines Color Area, Color Slider, Color Field, and Color Swatch components. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### ColorAreaRoot The root component that provides the color area context and state management. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `colorSpace` | The color space to operate in. | `"hsl" \| "rgb" \| "hsb"` | No | `"hsl"` | | `defaultValue` | The default color value (uncontrolled). | `string \| Color` | No | `"#ff0000"` | | `disabled` | When true, prevents the user from interacting with the area. | `boolean` | No | `false` | | `modelValue` | The color value (controlled). Can be a hex string or Color object. | `string \| Color` | No | - | | `name` | The name of the field. Submitted with its owning form as part of a name/value pair. | `string` | No | - | | `required` | When true, indicates that the user must set the value before the owning form can be submitted. | `boolean` | No | - | | `xChannel` | Color channel for the horizontal (x) axis. | `"hue" \| "saturation" \| "red" \| "green" \| "blue" \| "alpha" \| "lightness" \| "brightness"` | No | `"hue"` | | `xName` | The name of the x channel input element for form submission. | `string` | No | - | | `yChannel` | Color channel for the vertical (y) axis. | `"hue" \| "saturation" \| "red" \| "green" \| "blue" \| "alpha" \| "lightness" \| "brightness"` | No | `"saturation"` | | `yName` | The name of the y channel input element for form submission. | `string` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `change` | | `[value: string]` | | `changeEnd` | | `[value: string]` | | `update:color` | | `[value: Color]` | | `update:modelValue` | Event handler called when the value of the checkbox changes. | `[value: string]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `style` | CSS styles for the color area background gradient | `CSSProperties` | ### ColorAreaArea The interactive area component where users can select color values by clicking or dragging. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### ColorAreaThumb The draggable thumb component that indicates the current position in the color area. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"span"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ## Examples ### HSL Saturation/Lightness A common use case for color area is selecting saturation and lightness in HSL color space. ```vue ``` ### RGB Red/Green Selector Using RGB color space with red and green channels. ```vue ``` ### Disabled State Disable interaction with the color area. ```vue ``` ## Accessibility ### Keyboard Interactions | Key | Description | | --- | --- | | `ArrowLeft` | Decreases the x-axis channel value by one step. | | `ArrowRight` | Increases the x-axis channel value by one step. | | `ArrowUp` | Increases the y-axis channel value by one step. | | `ArrowDown` | Decreases the y-axis channel value by one step. | | `Shift + ArrowKey` | Changes values by 10 steps at a time. | | `PageUp` | Increases the y-axis channel value by a larger step. | | `PageDown` | Decreases the y-axis channel value by a larger step. | | `Home` | Jumps left (decreases x-axis value). | | `End` | Jumps right (increases x-axis value). | --- --- url: /docs/components/color-field.md description: An input field for entering and editing color values in various formats. --- # Color Field Alpha ## Features ## Installation Install the component from your command line. Looking for a complete color picker? Check out the [Color Picker example](/examples/color-picker) that combines Color Area, Color Slider, Color Field, and Color Swatch components. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### ColorFieldRoot The root component that provides the color field context and state management. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `channel` | The color channel to display. If not provided, displays hex value. | `"hue" \| "saturation" \| "red" \| "green" \| "blue" \| "alpha" \| "lightness" \| "brightness"` | No | - | | `colorSpace` | The color space to operate in when displaying a channel. | `"hsl" \| "rgb" \| "hsb"` | No | `"hsl"` | | `defaultValue` | The default color value (uncontrolled). | `string \| Color` | No | `"#000000"` | | `disabled` | When true, prevents the user from interacting with the field. | `boolean` | No | `false` | | `disableWheelChange` | When true, prevents the value from changing on wheel scroll. | `boolean` | No | `false` | | `locale` | The locale to use for number formatting. | `string` | No | - | | `modelValue` | The color value (controlled). Can be a hex string or Color object. | `string \| Color` | No | - | | `name` | The name of the field. Submitted with its owning form as part of a name/value pair. | `string` | No | - | | `placeholder` | Placeholder text when the field is empty. | `string` | No | - | | `readonly` | When true, the field is read-only. | `boolean` | No | `false` | | `required` | When true, indicates that the user must set the value before the owning form can be submitted. | `boolean` | No | - | | `step` | Custom step value for increment/decrement. Defaults to channel step or 1 for hex. | `number` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `update:color` | | `[value: Color]` | | `update:modelValue` | Event handler called when the value of the checkbox changes. | `[value: string]` | ### ColorFieldInput The input element for entering color values. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"input"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ## Examples ### Hex Color Input Basic hex color input field. ```vue ``` ### Channel Input Input for a specific color channel (e.g., hue). ```vue ``` ### With Wheel Control Disabled Prevent changing values with mouse wheel. ```vue ``` ### Read-only Mode Display the color value without allowing edits. ```vue ``` ## Accessibility ### Keyboard Interactions | Key | Description | | --- | --- | | `ArrowUp` | Increases the value by one step. | | `ArrowDown` | Decreases the value by one step. | | `PageUp` | Increases the value by 10 steps. | | `PageDown` | Decreases the value by 10 steps. | | `Home` | Sets the value to minimum. | | `End` | Sets the value to maximum. | | `Enter` | Commits the current input value. | --- --- url: /docs/components/color-slider.md description: A slider control for adjusting individual color channels. --- # Color Slider Alpha ## Features ## Installation Install the component from your command line. Looking for a complete color picker? Check out the [Color Picker example](/examples/color-picker) that combines Color Area, Color Slider, Color Field, and Color Swatch components. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### ColorSliderRoot The root component that provides the slider functionality and context. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"span"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `channel` | The color channel that this slider manipulates. | `"hue" \| "saturation" \| "red" \| "green" \| "blue" \| "alpha" \| "lightness" \| "brightness"` | Yes | - | | `colorSpace` | The color space to operate in. | `"hsl" \| "rgb" \| "hsb"` | No | `"hsl"` | | `defaultValue` | The default color value (uncontrolled). | `string \| Color` | No | `"#000000"` | | `dir` | The reading direction of the slider. | `"ltr" \| "rtl"` | No | - | | `disabled` | When true, prevents the user from interacting with the slider. | `boolean` | No | `false` | | `inverted` | Whether the slider is visually inverted. | `boolean` | No | `false` | | `modelValue` | The color value (controlled). Can be a hex string or Color object. | `string \| Color` | No | - | | `name` | The name of the field. Submitted with its owning form as part of a name/value pair. | `string` | No | - | | `orientation` | The orientation of the slider. | `"vertical" \| "horizontal"` | No | `"horizontal"` | | `required` | When true, indicates that the user must set the value before the owning form can be submitted. | `boolean` | No | - | | `step` | Custom step value for increment/decrement. Defaults to the channel's natural step. | `number` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `change` | | `[value: string]` | | `changeEnd` | | `[value: string]` | | `update:color` | | `[value: Color]` | | `update:modelValue` | Event handler called when the value of the checkbox changes. | `[value: string \| Color]` | ### ColorSliderTrack The track component that displays the color gradient background. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"span"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### ColorSliderThumb The draggable thumb component for selecting values. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"span"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `channelName` | The display name of the current channel | `string` | | `channelValue` | The current numeric value of the channel | `number` | ## Examples ### Hue Slider A horizontal hue slider in HSL color space. ```vue ``` ### Alpha Channel Slider for adjusting the alpha (opacity) channel. ```vue ``` ### Vertical Orientation A vertical slider for space-constrained layouts. ```vue ``` ### RGB Channel Sliders Sliders for individual RGB channels. ```vue ``` ### Custom Step Value Use a custom step increment for finer or coarser control. ```vue ``` ## Accessibility ### Keyboard Interactions | Key | Description | | --- | --- | | `ArrowLeft` | Decreases the value in horizontal orientation. | | `ArrowRight` | Increases the value in horizontal orientation. | | `ArrowUp` | Increases the value in vertical orientation. | | `ArrowDown` | Decreases the value in vertical orientation. | | `PageUp` | Increases the value by a larger step. | | `PageDown` | Decreases the value by a larger step. | | `Home` | Sets the value to minimum. | | `End` | Sets the value to maximum. | --- --- url: /docs/components/color-swatch.md description: >- A predefined color block that allows users to quickly select commonly used or brand-specific colors. --- # Color Swatch Alpha ## Features ## Installation Install the component from your command line. Looking for a complete color picker? Check out the [Color Picker example](/examples/color-picker) that combines Color Area, Color Slider, Color Field, and Color Swatch components. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### ColorSwatch The main component that displays a color swatch. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `color` | The color to display in the swatch as a hex string or Color object. Example: #16a372, #ff5733, or { space: 'hsl', h: 120, s: 100, l: 50, alpha: 1 }. | `string \| Color` | No | `""` | | `label` | Optional accessible label for the color. If omitted, the color name will be derived from the color value. | `string` | No | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `color` | | `string` | | `alpha` | | `number` | --- --- url: /docs/components/color-swatch-picker.md description: >- A component that allows users to select from a set of predefined colors, often used for themes or branding. --- # Color Swatch Picker Alpha ## Features ## Installation Install the component from your command line. Looking for a complete color picker? Check out the [Color Picker example](/examples/color-picker) that combines Color Area, Color Slider, Color Field, and Color Swatch components. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### ColorSwatchPickerRoot The main component that displays a color swatch picker. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `defaultValue` | The value of the listbox when initially rendered. Use when you do not need to control the state of the Listbox | `string \| string[]` | No | - | | `dir` | The reading direction of the listbox when applicable. If omitted, inherits globally from ConfigProvider or assumes LTR (left-to-right) reading mode. | `"ltr" \| "rtl"` | No | `"ltr"` | | `disabled` | When true, prevents the user from interacting with listbox | `boolean` | No | `false` | | `highlightOnHover` | When true, hover over item will trigger highlight | `boolean` | No | - | | `modelValue` | The controlled value of the listbox. Can be binded with v-model. | `string \| string[]` | No | - | | `multiple` | Whether multiple options can be selected or not. | `boolean` | No | - | | `name` | The name of the field. Submitted with its owning form as part of a name/value pair. | `string` | No | - | | `orientation` | The orientation of the listbox. Mainly so arrow navigation is done accordingly (left & right vs. up & down) | `"vertical" \| "horizontal"` | No | `"horizontal"` | | `required` | When true, indicates that the user must set the value before the owning form can be submitted. | `boolean` | No | - | | `selectionBehavior` | How multiple selection should behave in the collection. | `"replace" \| "toggle"` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `entryFocus` | Event handler called when container is being focused. Can be prevented. | `[event: CustomEvent]` | | `highlight` | Event handler when highlighted element changes. | `[payload: { ref: HTMLElement; value: AcceptableValue; }]` | | `leave` | Event handler called when the mouse leave the container | `[event: Event]` | | `update:modelValue` | Event handler called when the value changes. | `[value: AcceptableValue]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `modelValue` | | `string \| string[] \| undefined` | ### ColorSwatchPickerItem The item that represents a selectable color swatch. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | When true, prevents the user from interacting with the item. | `boolean` | No | - | | `value` | The color to display in the swatch as a hex string. Example: #16a372 or #ff5733. | `string` | Yes | - | **Events** | Name | Description | Type | | --- | --- | --- | | `select` | Event handler called when the selecting item. It can be prevented by calling event.preventDefault. | `[event: SelectEvent]` | ### ColorSwatchPickerItemSwatch The component that displays the color swatch within an item. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `label` | Optional accessible label for the color. If omitted, the color name will be derived from the color value. | `string` | No | - | ### ColorSwatchPickerItemIndicator The component that indicates the selected color swatch within an item. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | --- --- url: /docs/components/combobox.md description: Choose from a list of suggested values with full keyboard support. --- # Combobox ## Features ## Installation Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Root Contains all the parts of a Combobox **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `by` | Use this to compare objects by a particular field, or pass your own comparison function for complete control over how objects are compared. | `string \| ((a: T, b: T) => boolean)` | No | - | | `defaultOpen` | The open state of the combobox when it is initially rendered. Use when you do not need to control its open state. | `boolean` | No | - | | `defaultValue` | The value of the listbox when initially rendered. Use when you do not need to control the state of the Listbox | `T \| T[]` | No | - | | `dir` | The reading direction of the listbox when applicable. If omitted, inherits globally from ConfigProvider or assumes LTR (left-to-right) reading mode. | `"ltr" \| "rtl"` | No | - | | `disabled` | When true, prevents the user from interacting with listbox | `boolean` | No | - | | `highlightOnHover` | When true, hover over item will trigger highlight | `boolean` | No | `true` | | `ignoreFilter` | When true, disable the default filters | `boolean` | No | - | | `modelValue` | The controlled value of the listbox. Can be binded with v-model. | `T \| T[]` | No | - | | `multiple` | Whether multiple options can be selected or not. | `boolean` | No | - | | `name` | The name of the field. Submitted with its owning form as part of a name/value pair. | `string` | No | - | | `open` | The controlled open state of the Combobox. Can be binded with v-model:open. | `boolean` | No | - | | `openOnClick` | Whether to open the combobox when the input is clicked | `boolean` | No | `false` | | `openOnFocus` | Whether to open the combobox when the input is focused | `boolean` | No | `false` | | `required` | When true, indicates that the user must set the value before the owning form can be submitted. | `boolean` | No | - | | `resetModelValueOnClear` | When true the modelValue will be reset to null (or \[] if multiple) | `boolean` | No | `false` | | `resetSearchTermOnBlur` | Whether to reset the searchTerm when the Combobox input blurred | `boolean` | No | `true` | | `resetSearchTermOnSelect` | Whether to reset the searchTerm when the Combobox value is selected | `boolean` | No | `true` | **Events** | Name | Description | Type | | --- | --- | --- | | `highlight` | Event handler when highlighted element changes. | `[payload: { ref: HTMLElement; value: T; }]` | | `update:modelValue` | Event handler called when the value changes. | `[value: T]` | | `update:open` | Event handler called when the open state of the combobox changes. | `[value: boolean]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `open` | Current open state | `boolean` | | `modelValue` | Current active value | `T \| T[]` | ### Anchor Used as an anchor if you set `ComboboxContent`'s position to `popper`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `reference` | The reference (or anchor) element that is being referred to for positioning. If not provided will use the current component as anchor. | `ReferenceElement` | No | - | ### Input The input component to search through the combobox items. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"input"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `autoFocus` | Focus on element when mounted. | `boolean` | No | - | | `disabled` | When true, prevents the user from interacting with item | `boolean` | No | - | | `displayValue` | The display value of input for selected item. Does not work with multiple. | `((val: any) => string)` | No | - | | `modelValue` | The controlled value of the filter. Can be binded with v-model. | `string` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `update:modelValue` | Event handler called when the value changes. | `[string]` | ### Trigger The button that toggles the Combobox Content. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | When true, prevents the user from interacting with item | `boolean` | No | - | ### Cancel The button that clears the search term. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Empty Shown when none of the items match the query. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Portal When used, portals the content part into the `body`. You need to set `position="popper"` for `ComboboxContent` to make sure the position was automatically computed similar to `Popover` or `DropdownMenu`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `defer` | Defer the resolving of a Teleport target until other parts of the application have mounted (requires Vue 3.5.0+) reference | `boolean` | No | - | | `disabled` | Disable teleport and render the component inline reference | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | | `to` | Vue native teleport component prop :to reference | `string \| HTMLElement` | No | - | ### Content The component that pops out when the combobox is open. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `align` | The preferred alignment against the trigger. May change when collisions occur. | `"start" \| "center" \| "end"` | No | - | | `alignFlip` | Flip alignment when colliding with boundary. May only occur when prioritizePosition is true. | `boolean` | No | - | | `alignOffset` | An offset in pixels from the start or end alignment options. | `number` | No | - | | `arrowPadding` | The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners. | `number` | No | - | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `avoidCollisions` | When true, overrides the side and align preferences to prevent collisions with boundary edges. | `boolean` | No | - | | `bodyLock` | The document.body will be lock, and scrolling will be disabled. | `boolean` | No | - | | `collisionBoundary` | The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. | `Element \| (Element \| null)[] \| null` | No | - | | `collisionPadding` | The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }. | `number \| Partial>` | No | - | | `dir` | The reading direction of the popper content when applicable. If omitted, inherits globally from ConfigProvider or assumes LTR (left-to-right) reading mode. | `"ltr" \| "rtl"` | No | - | | `disableOutsidePointerEvents` | When true, hover/focus/click interactions will be disabled on elements outside the DismissableLayer. Users will need to click twice on outside elements to interact with them: once to close the DismissableLayer, and again to trigger the element. | `boolean` | No | - | | `disableUpdateOnLayoutShift` | Whether to disable the update position for the content when the layout shifted. | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | | `hideShiftedArrow` | When true, hides the arrow when it cannot be centered to the reference element. | `boolean` | No | - | | `hideWhenDetached` | Whether to hide the content when the trigger becomes fully occluded. | `boolean` | No | - | | `hideWhenEmpty` | When true, hides the content when there are no items matching the filter. | `boolean` | No | - | | `memoDependencies` | Reactive dependencies that should invalidate the memoized content subtree. | `unknown[]` | No | - | | `position` | The positioning mode to use, inline is the default and you can control the position using CSS. popper positions content in the same way as our other primitives, for example Popover or DropdownMenu. | `"inline" \| "popper"` | No | - | | `positionStrategy` | The type of CSS position property to use. | `"fixed" \| "absolute"` | No | - | | `prioritizePosition` | Force content to be position within the viewport. Might overlap the reference element, which may not be desired. | `boolean` | No | - | | `reference` | The custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element. | `ReferenceElement` | No | - | | `side` | The preferred side of the trigger to render against when open. Will be reversed when collisions occur and avoidCollisions is enabled. | `"top" \| "right" \| "bottom" \| "left"` | No | - | | `sideFlip` | Flip to the opposite side when colliding with boundary. | `boolean` | No | - | | `sideOffset` | The distance in pixels from the trigger. | `number` | No | - | | `sticky` | 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. | `"partial" \| "always"` | No | - | | `updatePositionStrategy` | Strategy to update the position of the floating element on every animation frame. | `"always" \| "optimized"` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `escapeKeyDown` | Event handler called when the escape key is down. Can be prevented. | `[event: KeyboardEvent]` | | `focusOutside` | Event handler called when the focus moves outside of the DismissableLayer. Can be prevented. | `[event: FocusOutsideEvent]` | | `interactOutside` | Event handler called when an interaction happens outside the DismissableLayer. Specifically, when a pointerdown event happens outside or focus moves outside of it. Can be prevented. | `[event: PointerDownOutsideEvent \| FocusOutsideEvent]` | | `pointerDownOutside` | Event handler called when a pointerdown event happens outside of the DismissableLayer. Can be prevented. | `[event: PointerDownOutsideEvent]` | ### Viewport The scrolling viewport that contains all of the items. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `nonce` | Will add nonce attribute to the style tag which can be used by Content Security Policy. If omitted, inherits globally from ConfigProvider. | `string` | No | - | ### Item The component that contains the combobox items. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | When true, prevents the user from interacting with the item. | `boolean` | No | - | | `textValue` | A string representation of the item contents. If the children are not plain text, then the textValue prop must also be set to a plain text representation, which will be used for autocomplete in the ComboBox. | `string` | No | - | | `value` | The value given as data when submitted with a name. | `T` | Yes | - | **Events** | Name | Description | Type | | --- | --- | --- | | `select` | Event handler called when the selecting item. It can be prevented by calling event.preventDefault. | `[event: SelectEvent]` | ### ItemIndicator Renders when the item is selected. You can style this element directly, or you can use it as a wrapper to put an icon into, or both. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"span"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Group Used to group multiple items. use in conjunction with `ComboboxLabel` to ensure good accessibility via automatic labelling. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Label Used to render the label of a group. It won't be focusable using arrow keys. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `for` | | `string` | No | - | ### Separator Used to visually separate items in the Combobox **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Arrow An optional arrow element to render alongside the content. This can be used to help visually link the trigger with the `ComboboxContent`. Must be rendered inside `ComboboxContent`. Only available when `position` is set to `popper`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"svg"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `height` | The height of the arrow in pixels. | `number` | No | `5` | | `rounded` | When true, render the rounded version of arrow. Do not work with as/asChild | `boolean` | No | - | | `width` | The width of the arrow in pixels. | `number` | No | `10` | ### Virtualizer Virtual container to achieve list virtualization. Combobox items **must** be filtered manually before passing them over to the virtualizer. See [example below](#virtualized-combobox-with-working-filtering). See the [virtualization guide](../guides/virtualization.md) for more general info on virtualization. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `estimateSize` | Estimated size (in px) of each item | `number \| ((index: number) => number)` | No | - | | `options` | List of items | `T` | Yes | - | | `overscan` | Number of items rendered outside the visible area | `number` | No | - | | `textContent` | Text content for each item to achieve type-ahead feature | `((option: T) => string)` | No | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `option` | | `T` | | `virtualizer` | | `Virtualizer` | | `virtualItem` | | `VirtualItem` | ## Examples ### Binding objects as values Unlike native HTML form controls which only allow you to provide strings as values, `reka-ui` supports binding complex objects as well. Make sure to set the `displayValue` prop to set the input value on item selection. ```vue line=12,17,23 ``` ### Selecting multiple values The `Combobox` component allows you to select multiple values. You can enable this by providing an array of values instead of a single value. ```vue line=12,17-18 ``` ### Custom filtering Internally, `ComboboxRoot` will filter the item based on the rendered text. However, you may also provide your own custom filtering logic together with setting `ignoreFilter="true"`. ```vue line=15,16,22,28 ``` ### Custom label By default the `Combobox` will use the input contents as the label for screenreaders. If you'd like more control over what is announced to assistive technologies, use the [Label](/docs/components/label) component. ```vue line=8,10 ``` ### With disabled items You can add special styles to disabled items via the `data-disabled` attribute. ```vue line=19 ``` ```css line=2 /* styles.css */ .ComboboxItem[data-disabled] { color: "gainsboro"; } ``` ### With separators Use the `Separator` part to add a separator between items. ```vue line=21 ``` ### With grouped items Use the `Group` and `Label` parts to group items in a section. ```vue line=19,20,24 ``` ### With complex items You can use custom content in your items. ```vue line=21 ``` ### Prevent select behavior By default, selecting `ComboboxItem` would close the content, and update the `modelValue` with the provided value. You can prevent this behavior by preventing default `@select.prevent`. ```vue line=11 ``` ### Virtualized combobox with working filtering Combobox items **must** be filtered manually before passing them over to the virtualizer. See the [virtualization guide](../guides/virtualization.md) for more general info on virtualization. ```vue line=9-10,17,19-28 ``` ## Accessibility Adheres to the [Combobox WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/). See the W3C [Combobox Autocomplete List](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-autocomplete-list/) example for more information. ### Keyboard Interactions ## Custom APIs Create your own API by abstracting the primitive parts into your own component. ### Command Menu Combobox can be use to build your own Command Menu. #### Usage ```vue ``` #### Implementation ```ts // your-command.ts export { default as Command } from 'Command.vue' export { default as CommandItem } from 'CommandItem.vue' ``` ```vue ``` ```vue ``` --- --- url: /docs/guides/composition.md description: >- Use the `asChild` prop to compose Reka's functionality onto alternative element types or your own Vue components. --- # Composition Use the `asChild` prop to compose Reka's functionality onto alternative element types or your own Vue components. All Reka UI parts that render a DOM element accept an `asChild` prop. When `asChild` is set to `true`, Reka UI will not render a default DOM element, instead passing the props and behavior required to make it functional to the first child of the slots. ## Changing the element type In the majority of cases you shouldn’t need to modify the element type as Reka has been designed to provide the most appropriate defaults. However, there are cases where it is helpful to do so. A good example is with `TooltipTrigger`. By default this part is rendered as a `button`, though you may want to add a tooltip to a link (`a` tag) as well. Let's see how you can achieve this using `asChild`: ```vue{7} ``` If you do decide to change the underlying element type, it is your responsibility to ensure it remains accessible and functional. In the case of `TooltipTrigger` for example, it must be a focusable element that can respond to pointer and keyboard events. If you were to switch it to a `div`, it would no longer be accessible. In reality, you will rarely modify the underlying DOM element like we've seen above. Instead it's more common to use your own Vue components. This is especially true for most `Trigger` parts, as you usually want to compose the functionality with the custom buttons and links in your design system. ## Composing with your own Vue components This works exactly the same as above, you pass `asChild` to the part and then wrap your own component with it. However, there are a few gotchas to be aware of. ## Composing multiple primitives `asChild` can be used as deeply as you need to. This means it is a great way to compose multiple primitive's behavior together. Here is an example of how you can compose `TooltipTrigger` and `DialogTrigger` together with your own button: ```vue{9,10} ``` --- --- url: /docs/utilities/config-provider.md description: Wraps your app to provide global configurations. --- # Config Provider ## Anatomy Import the component. ```vue ``` ## API Reference ### Config Provider When creating localized apps that require right-to-left (RTL) reading direction, you need to wrap your application with the `ConfigProvider` component to ensure all of the primitives adjust their behavior based on the `dir` prop. You can also change the global behavior of `bodylock` for components such as `Alert`, `DropdownMenu` and etc to fit your layout to prevent any [content shifts](https://github.com/unovue/reka-ui/issues/385). **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `dir` | The global reading direction of your application. This will be inherited by all primitives. | `"ltr" \| "rtl"` | No | `"ltr"` | | `locale` | The global locale of your application. This will be inherited by all primitives. | `string` | No | `"en"` | | `nonce` | The global nonce value of your application. This will be inherited by the related primitives. | `string` | No | - | | `scrollBody` | The global scroll body behavior of your application. This will be inherited by the related primitives. | `boolean \| ScrollBodyOption` | No | `true` | | `teleportTo` | The global default teleport target for all portalled primitives (e.g. Dialog, Popover, Tooltip). Individual \*Portal components can still override this via their own to prop. Useful when rendering inside a custom element / shadow DOM. | `string \| HTMLElement` | No | - | | `useId` | The global useId injection as a workaround for preventing hydration issue. | `(() => string)` | No | - | ## Example Use the config provider. Set global direction to `rtl`, and scroll body behavior to `false` (will not set any padding/margin). ```vue ``` ## Hydration issue `ConfigProvider` can accept a custom `useId` function for frameworks that need to provide their own SSR-stable ID source. Reka UI uses this function before Vue's native `useId`, so every primitive that generates accessibility IDs follows the same app-provided source. This is useful in Nuxt projects where prerendered HTML and client hydration can use different Vue app ID prefixes. Pass Nuxt's [`useId`](https://nuxt.com/docs/api/composables/use-id) through `ConfigProvider` so Reka-generated IDs stay stable across server and client rendering. > Inspired by [Headless UI](https://github.com/tailwindlabs/headlessui/pull/2959) ```vue ``` --- --- url: /docs/components/context-menu.md description: >- Displays a menu located at the pointer, triggered by a right-click or a long-press. --- # Context Menu ## Features ## Installation Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference Adheres to the [Menu WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu) and uses [roving tabindex](https://www.w3.org/TR/wai-aria-practices-1.2/examples/menu-button/menu-button-actions.html) to manage focus movement among menu items. ### Root Contains all the parts of a context menu. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `dir` | The reading direction of the combobox when applicable. If omitted, inherits globally from ConfigProvider or assumes LTR (left-to-right) reading mode. | `"ltr" \| "rtl"` | No | - | | `modal` | The modality of the dropdown menu. When set to true, interaction with outside elements will be disabled and only menu content will be visible to screen readers. | `boolean` | No | `true` | | `pressOpenDelay` | The duration from when the trigger is pressed until the menu opens. | `number` | No | `700` | **Events** | Name | Description | Type | | --- | --- | --- | | `update:open` | Event handler called when the open state of the submenu changes. | `[payload: boolean]` | ### Trigger The area that opens the context menu. Wrap it around the target you want the context menu to open from when right-clicking (or using the relevant keyboard shortcuts). **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"span"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | When true, the context menu would not open when right-clicking. Note that this will also restore the native context menu. | `boolean` | No | `false` | ### Portal When used, portals the content part into the `body`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `defer` | Defer the resolving of a Teleport target until other parts of the application have mounted (requires Vue 3.5.0+) reference | `boolean` | No | - | | `disabled` | Disable teleport and render the component inline reference | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | | `to` | Vue native teleport component prop :to reference | `string \| HTMLElement` | No | - | ### Content The component that pops out in an open context menu. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `alignFlip` | Flip alignment when colliding with boundary. May only occur when prioritizePosition is true. | `boolean` | No | - | | `alignOffset` | An offset in pixels from the start or end alignment options. | `number` | No | `0` | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `avoidCollisions` | When true, overrides the side and align preferences to prevent collisions with boundary edges. | `boolean` | No | `true` | | `collisionBoundary` | The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. | `Element \| (Element \| null)[] \| null` | No | `[]` | | `collisionPadding` | The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }. | `number \| Partial>` | No | `0` | | `disableUpdateOnLayoutShift` | Whether to disable the update position for the content when the layout shifted. | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | | `hideShiftedArrow` | When true, hides the arrow when it cannot be centered to the reference element. | `boolean` | No | - | | `hideWhenDetached` | Whether to hide the content when the trigger becomes fully occluded. | `boolean` | No | `false` | | `loop` | When true, keyboard navigation will loop from last item to first, and vice versa. | `boolean` | No | - | | `memoDependencies` | Reactive dependencies that should invalidate the memoized content subtree. | `unknown[]` | No | - | | `positionStrategy` | The type of CSS position property to use. | `"fixed" \| "absolute"` | No | - | | `prioritizePosition` | Force content to be position within the viewport. Might overlap the reference element, which may not be desired. | `boolean` | No | - | | `reference` | The custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element. | `ReferenceElement` | No | - | | `sideFlip` | Flip to the opposite side when colliding with boundary. | `boolean` | No | - | | `sticky` | 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. | `"partial" \| "always"` | No | `"partial"` | **Events** | Name | Description | Type | | --- | --- | --- | | `closeAutoFocus` | Event handler called when auto-focusing on close. Can be prevented. | `[event: Event]` | | `escapeKeyDown` | Event handler called when the escape key is down. Can be prevented. | `[event: KeyboardEvent]` | | `focusOutside` | Event handler called when the focus moves outside of the DismissableLayer. Can be prevented. | `[event: FocusOutsideEvent]` | | `interactOutside` | Event handler called when an interaction happens outside the DismissableLayer. Specifically, when a pointerdown event happens outside or focus moves outside of it. Can be prevented. | `[event: PointerDownOutsideEvent \| FocusOutsideEvent]` | | `pointerDownOutside` | Event handler called when a pointerdown event happens outside of the DismissableLayer. Can be prevented. | `[event: PointerDownOutsideEvent]` | ### Arrow An optional arrow element to render alongside a submenu. This can be used to help visually link the trigger item with the `ContextMenu.Content`. Must be rendered inside `ContextMenu.Content`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"svg"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `height` | The height of the arrow in pixels. | `number` | No | `5` | | `rounded` | When true, render the rounded version of arrow. Do not work with as/asChild | `boolean` | No | - | | `width` | The width of the arrow in pixels. | `number` | No | `10` | ### Item The component that contains the context menu items. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | When true, prevents the user from interacting with the item. | `boolean` | No | - | | `textValue` | Optional text used for typeahead purposes. By default the typeahead behavior will use the .textContent of the item. Use this when the content is complex, or you have non-textual content inside. | `string` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `select` | Event handler called when the user selects an item (via mouse or keyboard). Calling event.preventDefault in this handler will prevent the menu from closing when selecting that item. | `[event: Event]` | ### Group Used to group multiple `ContextMenu.Item`s. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Label Used to render a label. It won't be focusable using arrow keys. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### CheckboxItem An item that can be controlled and rendered like a checkbox. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | When true, prevents the user from interacting with the item. | `boolean` | No | - | | `modelValue` | The controlled checked state of the item. Can be used as v-model. | `false \| true \| "indeterminate"` | No | - | | `textValue` | Optional text used for typeahead purposes. By default the typeahead behavior will use the .textContent of the item. Use this when the content is complex, or you have non-textual content inside. | `string` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `select` | Event handler called when the user selects an item (via mouse or keyboard). Calling event.preventDefault in this handler will prevent the menu from closing when selecting that item. | `[event: Event]` | | `update:modelValue` | Event handler called when the value changes. | `[payload: boolean]` | ### RadioGroup Used to group multiple `ContextMenu.RadioItem`s. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `modelValue` | The value of the selected item in the group. | `AcceptableValue` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `update:modelValue` | Event handler called when the value changes. | `[payload: AcceptableValue]` | ### RadioItem An item that can be controlled and rendered like a radio. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | When true, prevents the user from interacting with the item. | `boolean` | No | - | | `textValue` | Optional text used for typeahead purposes. By default the typeahead behavior will use the .textContent of the item. Use this when the content is complex, or you have non-textual content inside. | `string` | No | - | | `value` | The unique value of the item. | `AcceptableValue` | Yes | - | **Events** | Name | Description | Type | | --- | --- | --- | | `select` | Event handler called when the user selects an item (via mouse or keyboard). Calling event.preventDefault in this handler will prevent the menu from closing when selecting that item. | `[event: Event]` | ### ItemIndicator Renders when the parent `ContextMenu.CheckboxItem` or `ContextMenu.RadioItem` is checked. You can style this element directly, or you can use it as a wrapper to put an icon into, or both. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | ### Separator Used to visually separate items in the context menu. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Sub Contains all the parts of a submenu. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `defaultOpen` | The open state of the submenu when it is initially rendered. Use when you do not need to control its open state. | `boolean` | No | - | | `open` | The controlled open state of the menu. Can be used as v-model:open. | `boolean` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `update:open` | Event handler called when the open state of the submenu changes. | `[payload: boolean]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `open` | Current open state | `boolean` | ### SubTrigger An item that opens a submenu. Must be rendered inside `ContextMenu.Sub`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | When true, prevents the user from interacting with the item. | `boolean` | No | - | | `textValue` | Optional text used for typeahead purposes. By default the typeahead behavior will use the .textContent of the item. Use this when the content is complex, or you have non-textual content inside. | `string` | No | - | ### SubContent The component that pops out when a submenu is open. Must be rendered inside `ContextMenu.Sub`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `alignFlip` | Flip alignment when colliding with boundary. May only occur when prioritizePosition is true. | `boolean` | No | - | | `alignOffset` | An offset in pixels from the start or end alignment options. | `number` | No | - | | `arrowPadding` | The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners. | `number` | No | - | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `avoidCollisions` | When true, overrides the side and align preferences to prevent collisions with boundary edges. | `boolean` | No | - | | `collisionBoundary` | The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. | `Element \| (Element \| null)[] \| null` | No | - | | `collisionPadding` | The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }. | `number \| Partial>` | No | - | | `disableUpdateOnLayoutShift` | Whether to disable the update position for the content when the layout shifted. | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | | `hideShiftedArrow` | When true, hides the arrow when it cannot be centered to the reference element. | `boolean` | No | - | | `hideWhenDetached` | Whether to hide the content when the trigger becomes fully occluded. | `boolean` | No | - | | `loop` | When true, keyboard navigation will loop from last item to first, and vice versa. | `boolean` | No | - | | `memoDependencies` | Reactive dependencies that should invalidate the memoized content subtree. | `unknown[]` | No | - | | `positionStrategy` | The type of CSS position property to use. | `"fixed" \| "absolute"` | No | - | | `prioritizePosition` | Force content to be position within the viewport. Might overlap the reference element, which may not be desired. | `boolean` | No | - | | `reference` | The custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element. | `ReferenceElement` | No | - | | `sideFlip` | Flip to the opposite side when colliding with boundary. | `boolean` | No | - | | `sideOffset` | The distance in pixels from the trigger. | `number` | No | - | | `sticky` | 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. | `"partial" \| "always"` | No | - | | `updatePositionStrategy` | Strategy to update the position of the floating element on every animation frame. | `"always" \| "optimized"` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `closeAutoFocus` | Event handler called when auto-focusing on close. Can be prevented. | `[event: Event]` | | `entryFocus` | Event handler called when container is being focused. Can be prevented. | `[event: Event]` | | `escapeKeyDown` | Event handler called when the escape key is down. Can be prevented. | `[event: KeyboardEvent]` | | `focusOutside` | Event handler called when the focus moves outside of the DismissableLayer. Can be prevented. | `[event: FocusOutsideEvent]` | | `interactOutside` | Event handler called when an interaction happens outside the DismissableLayer. Specifically, when a pointerdown event happens outside or focus moves outside of it. Can be prevented. | `[event: PointerDownOutsideEvent \| FocusOutsideEvent]` | | `openAutoFocus` | Event handler called when auto-focusing on open. Can be prevented. | `[event: Event]` | | `pointerDownOutside` | Event handler called when a pointerdown event happens outside of the DismissableLayer. Can be prevented. | `[event: PointerDownOutsideEvent]` | ## Examples ### With submenus You can create submenus by using `ContextMenuSub` in combination with its parts. ```vue line=24-33 ``` ### With disabled items You can add special styles to disabled items via the `data-disabled` attribute. ```vue line=12 ``` ```css line=2 /* styles.css */ .ContextMenuItem[data-disabled] { color: gainsboro; } ``` ### With separators Use the `Separator` part to add a separator between items. ```vue line=7,18,20 ``` ### With labels Use the `Label` part to help label a section. ```vue line=5,17 ``` ### With checkbox items Use the `CheckboxItem` part to add an item that can be checked. ```vue line=3,25-30 ``` ### With radio items Use the `RadioGroup` and `RadioItem` parts to add an item that can be checked amongst others. ```vue line=8,9,24-43 ``` ### With complex items You can add extra decorative elements in the `Item` parts, such as images. ```vue line=11,15 ``` ### Constrain the content/sub-content size You may want to constrain the width of the content (or sub-content) so that it matches the trigger (or sub-trigger) width. You may also want to constrain its height to not exceed the viewport. We expose several CSS custom properties such as `--reka-context-menu-trigger-width` and `--reka-context-menu-content-available-height` to support this. Use them to constrain the content dimensions. ```vue line=9 ``` ```css line=3-4 /* styles.css */ .ContextMenuContent { width: var(--reka-context-menu-trigger-width); max-height: var(--reka-context-menu-content-available-height); } ``` ### Origin-aware animations We expose a CSS custom property `--reka-context-menu-content-transform-origin`. Use it to animate the content from its computed origin based on `side`, `sideOffset`, `align`, `alignOffset` and any collisions. ```vue line=9 ``` ```css line=3 /* styles.css */ .ContextMenuContent { transform-origin: var(--reka-context-menu-content-transform-origin); animation: scaleIn 0.5s ease-out; } @keyframes scaleIn { from { opacity: 0; transform: scale(0); } to { opacity: 1; transform: scale(1); } } ``` ### Collision-aware animations We expose `data-side` and `data-align` attributes. Their values will change at runtime to reflect collisions. Use them to create collision and direction-aware animations. ```vue line=9 ``` ```css line=6-11 /* styles.css */ .ContextMenuContent { animation-duration: 0.6s; animation-timing-function: cubic-bezier(0.16, 1, 0.3, 1); } .ContextMenuContent[data-side="top"] { animation-name: slideUp; } .ContextMenuContent[data-side="bottom"] { animation-name: slideDown; } @keyframes slideUp { from { opacity: 0; transform: translateY(10px); } to { opacity: 1; transform: translateY(0); } } @keyframes slideDown { from { opacity: 0; transform: translateY(-10px); } to { opacity: 1; transform: translateY(0); } } ``` ## Accessibility Uses [roving tabindex](https://www.w3.org/WAI/ARIA/apg/patterns/kbd_roving_tabindex) to manage focus movement among menu items. ### Keyboard Interactions --- --- url: /docs/guides/controlled-state.md description: How to work with controlled vs. uncontrolled state in Reka UI. --- # Controlled State Reka UI provides flexible state management for components, allowing developers to use either **controlled** or **uncontrolled** state. Understanding when to use each approach ensures better integration with Vue's reactivity system. *** ## Controlled vs. Uncontrolled State ### Controlled State A **controlled** component receives its state as a prop and requires explicit updates via event listeners. The parent component manages and synchronizes the state. #### Example: Controlled `SwitchRoot` ```vue ``` **How it works:** * The `SwitchRoot` component’s state is managed by the `isActive` ref. * The `@update:modelValue` event ensures updates propagate correctly. - You need to sync state with Vuex, Pinia, or an API. - Multiple components rely on the same state. - You want fine-grained control over updates. #### Using v-model with Controlled Components Vue’s `v-model` syntax provides a convenient way to bind values to controlled components in Reka UI. It automatically handles passing the value and listening for updates. Example: Using `v-model` with `SwitchRoot` ```vue ``` ### Uncontrolled State An **uncontrolled** component manages its own state internally, without requiring a parent-controlled prop. Instead of `modelValue`, Reka UI components use `defaultValue` to initialize state. #### Example: Uncontrolled `SwitchRoot` ```vue ``` **How it works:** * The `SwitchRoot` initializes its state with `defaultValue`. * State changes occur internally without external control. - The component does not need to sync with external logic. - You want a simpler setup without explicit state management. - The state is local and does not impact other components. ## Common Mistakes & Fixes ### 1. Forgetting `@update:modelValue` ```vue ``` ### 2. Using `modelValue` Instead of `defaultValue` ```vue ``` ### 3. Not Providing a Setter for Computed Props ```ts // ❌ Incorrect: const isActive = computed(() => store.state.toggleState) // ✅ Correct: const isActive = computed({ get: () => store.state.toggleState, set: val => store.commit('setToggleState', val) }) ``` --- --- url: /docs/components/date-field.md description: Enables users to input specific dates within a designated field. --- # Date Field Alpha ## Features ## Preface The component depends on the [@internationalized/date](https://react-spectrum.adobe.com/internationalized/date/index.html) package, which solves a lot of the problems that come with working with dates and times in JavaScript. We highly recommend reading through the documentation for the package to get a solid feel for how it works, and you'll need to install it in your project to use the date-related components. ## Installation Install the date package. Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Root Contains all the parts of a date field **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `defaultPlaceholder` | The default placeholder date | `DateValue` | No | - | | `defaultValue` | The default value for the calendar | `DateValue` | No | - | | `dir` | The reading direction of the date field when applicable. If omitted, inherits globally from ConfigProvider or assumes LTR (left-to-right) reading mode. | `"ltr" \| "rtl"` | No | - | | `disabled` | Whether or not the date field is disabled | `boolean` | No | `false` | | `granularity` | The granularity to use for formatting times. 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 | `"day" \| "hour" \| "minute" \| "second"` | No | - | | `hideTimeZone` | Whether or not to hide the time zone segment of the field | `boolean` | No | - | | `hourCycle` | The hour cycle used for formatting times. Defaults to the local preference | `12 \| 24` | No | - | | `id` | Id of the element | `string` | No | - | | `isDateUnavailable` | A function that returns whether or not a date is unavailable | `Matcher` | No | - | | `locale` | The locale to use for formatting dates | `string` | No | - | | `maxValue` | The maximum date that can be selected | `DateValue` | No | - | | `minValue` | The minimum date that can be selected | `DateValue` | No | - | | `modelValue` | The controlled value of the field. Can be bound as v-model. | `DateValue \| null` | No | - | | `name` | The name of the field. Submitted with its owning form as part of a name/value pair. | `string` | No | - | | `placeholder` | 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 view | `DateValue` | No | - | | `readonly` | Whether or not the date field is readonly | `boolean` | No | `false` | | `required` | When true, indicates that the user must set the value before the owning form can be submitted. | `boolean` | No | - | | `step` | The stepping interval for the time fields. Defaults to 1. | `DateStep` | No | - | | `stepSnapping` | Whether to enforce snapping the time value to the nearest step increment after input. Defaults to false. | `boolean` | No | `false` | **Events** | Name | Description | Type | | --- | --- | --- | | `update:modelValue` | Event handler called whenever the model value changes | `[date: DateValue]` | | `update:placeholder` | Event handler called whenever the placeholder value changes | `[date: DateValue]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `modelValue` | The current date of the field | `DateValue \| undefined` | | `segments` | The date field segment contents | `{ part: SegmentPart; value: string; }[]` | | `isInvalid` | Value if the input is invalid | `boolean` | **Methods** | Name | Description | Type | | --- | --- | --- | | `setFocusedElement` | Helper to set the focused element inside the DateField | `(el: HTMLElement) => void` | ### Input Contains the date field segments **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `part` | The part of the date to render | `"day" \| "month" \| "year" \| "hour" \| "minute" \| "second" \| "dayPeriod" \| "literal" \| "timeZoneName"` | Yes | - | ## Accessibility ### Keyboard Interactions --- --- url: /docs/components/date-picker.md description: >- Facilitates the selection of dates through an input and calendar-based interface. --- # Date Picker Alpha ## Features ## Preface The component depends on the [@internationalized/date](https://react-spectrum.adobe.com/internationalized/date/index.html) package, which solves a lot of the problems that come with working with dates and times in JavaScript. We highly recommend reading through the documentation for the package to get a solid feel for how it works, and you'll need to install it in your project to use the date-related components. ## Installation Install the date package. Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Root Contains all the parts of a date picker **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `closeOnSelect` | Whether or not to close the popover on date select | `boolean` | No | `false` | | `defaultOpen` | The open state of the popover when it is initially rendered. Use when you do not need to control its open state. | `boolean` | No | `false` | | `defaultPlaceholder` | The default placeholder date | `DateValue` | No | - | | `defaultValue` | The default value for the calendar | `DateValue` | No | - | | `dir` | The reading direction of the date field when applicable. If omitted, inherits globally from ConfigProvider or assumes LTR (left-to-right) reading mode. | `"ltr" \| "rtl"` | No | - | | `disabled` | Whether or not the date field is disabled | `boolean` | No | `false` | | `fixedWeeks` | Whether or not to always display 6 weeks in the calendar | `boolean` | No | `false` | | `granularity` | The granularity to use for formatting times. 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 | `"day" \| "hour" \| "minute" \| "second"` | No | - | | `hideTimeZone` | Whether or not to hide the time zone segment of the field | `boolean` | No | - | | `hourCycle` | The hour cycle used for formatting times. Defaults to the local preference | `12 \| 24` | No | - | | `id` | Id of the element | `string` | No | - | | `isDateDisabled` | A function that returns whether or not a date is disabled | `Matcher` | No | - | | `isDateUnavailable` | A function that returns whether or not a date is unavailable | `Matcher` | No | - | | `locale` | The locale to use for formatting dates | `string` | No | - | | `maxValue` | The maximum date that can be selected | `DateValue` | No | - | | `minValue` | The minimum date that can be selected | `DateValue` | No | - | | `modal` | The modality of the popover. When set to true, interaction with outside elements will be disabled and only popover content will be visible to screen readers. | `boolean` | No | `false` | | `modelValue` | The controlled value of the field. Can be bound as v-model. | `DateValue \| null` | No | - | | `name` | The name of the field. Submitted with its owning form as part of a name/value pair. | `string` | No | - | | `numberOfMonths` | The number of months to display at once | `number` | No | `1` | | `open` | The controlled open state of the popover. | `boolean` | No | - | | `pagedNavigation` | This property causes the previous and next buttons to navigate by the number of months displayed at once, rather than one month | `boolean` | No | `false` | | `placeholder` | 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 view | `DateValue` | No | - | | `preventDeselect` | Whether or not to prevent the user from deselecting a date without selecting another date first | `boolean` | No | `false` | | `readonly` | Whether or not the date field is readonly | `boolean` | No | `false` | | `required` | When true, indicates that the user must set the value before the owning form can be submitted. | `boolean` | No | - | | `step` | The stepping interval for the time fields. Defaults to 1. | `DateStep` | No | - | | `stepSnapping` | Whether to enforce snapping the time value to the nearest step increment after input. Defaults to false. | `boolean` | No | - | | `weekdayFormat` | The format to use for the weekday strings provided via the weekdays slot prop | `"narrow" \| "short" \| "long"` | No | `"narrow"` | | `weekStartsOn` | The day of the week to start the calendar on | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `update:modelValue` | Event handler called whenever the model value changes | `[date: DateValue]` | | `update:open` | Event handler called when the open state of the submenu changes. | `[value: boolean]` | | `update:placeholder` | Event handler called whenever the placeholder value changes | `[date: DateValue]` | ### Field Contains the date picker date field segments and trigger **Slots** | Name | Description | Type | | --- | --- | --- | | `segments` | | `{ part: SegmentPart; value: string; }[]` | | `modelValue` | | `DateValue \| undefined` | ### Input Contains the date picker date field segments **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `part` | The part of the date to render | `"day" \| "month" \| "year" \| "hour" \| "minute" \| "second" \| "dayPeriod" \| "literal" \| "timeZoneName"` | Yes | - | ### Trigger The button that toggles the popover. By default, the `DatePickerContent` will position itself against the trigger. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Content The component that pops out when the popover is open. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `align` | The preferred alignment against the trigger. May change when collisions occur. | `"start" \| "center" \| "end"` | No | - | | `alignFlip` | Flip alignment when colliding with boundary. May only occur when prioritizePosition is true. | `boolean` | No | - | | `alignOffset` | An offset in pixels from the start or end alignment options. | `number` | No | - | | `arrowPadding` | The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners. | `number` | No | - | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `avoidCollisions` | When true, overrides the side and align preferences to prevent collisions with boundary edges. | `boolean` | No | - | | `collisionBoundary` | The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. | `Element \| (Element \| null)[] \| null` | No | - | | `collisionPadding` | The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }. | `number \| Partial>` | No | - | | `dir` | The reading direction of the popper content when applicable. If omitted, inherits globally from ConfigProvider or assumes LTR (left-to-right) reading mode. | `"ltr" \| "rtl"` | No | - | | `disableOutsidePointerEvents` | When true, hover/focus/click interactions will be disabled on elements outside the DismissableLayer. Users will need to click twice on outside elements to interact with them: once to close the DismissableLayer, and again to trigger the element. | `boolean` | No | - | | `disableUpdateOnLayoutShift` | Whether to disable the update position for the content when the layout shifted. | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | | `hideShiftedArrow` | When true, hides the arrow when it cannot be centered to the reference element. | `boolean` | No | - | | `hideWhenDetached` | Whether to hide the content when the trigger becomes fully occluded. | `boolean` | No | - | | `memoDependencies` | Reactive dependencies that should invalidate the memoized content subtree. | `unknown[]` | No | - | | `portal` | Props to control the portal wrapped around the content. | `PopoverPortalProps` | No | - | | `positionStrategy` | The type of CSS position property to use. | `"fixed" \| "absolute"` | No | - | | `prioritizePosition` | Force content to be position within the viewport. Might overlap the reference element, which may not be desired. | `boolean` | No | - | | `reference` | The custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element. | `ReferenceElement` | No | - | | `side` | The preferred side of the trigger to render against when open. Will be reversed when collisions occur and avoidCollisions is enabled. | `"top" \| "right" \| "bottom" \| "left"` | No | - | | `sideFlip` | Flip to the opposite side when colliding with boundary. | `boolean` | No | - | | `sideOffset` | The distance in pixels from the trigger. | `number` | No | - | | `sticky` | 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. | `"partial" \| "always"` | No | - | | `updatePositionStrategy` | Strategy to update the position of the floating element on every animation frame. | `"always" \| "optimized"` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `closeAutoFocus` | Event handler called when auto-focusing on close. Can be prevented. | `[event: Event]` | | `escapeKeyDown` | Event handler called when the escape key is down. Can be prevented. | `[event: KeyboardEvent]` | | `focusOutside` | Event handler called when the focus moves outside of the DismissableLayer. Can be prevented. | `[event: FocusOutsideEvent]` | | `interactOutside` | Event handler called when an interaction happens outside the DismissableLayer. Specifically, when a pointerdown event happens outside or focus moves outside of it. Can be prevented. | `[event: PointerDownOutsideEvent \| FocusOutsideEvent]` | | `openAutoFocus` | Event handler called when auto-focusing on open. Can be prevented. | `[event: Event]` | | `pointerDownOutside` | Event handler called when a pointerdown event happens outside of the DismissableLayer. Can be prevented. | `[event: PointerDownOutsideEvent]` | ### Arrow An optional arrow element to render alongside the popover. This can be used to help visually link the anchor with the `DatePickerContent`. Must be rendered inside `DatePickerContent`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `height` | The height of the arrow in pixels. | `number` | No | - | | `rounded` | When true, render the rounded version of arrow. Do not work with as/asChild | `boolean` | No | - | | `width` | The width of the arrow in pixels. | `number` | No | - | ### Close The button that closes an open date picker. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Anchor An optional element to position the `DatePickerContent` against. If this part is not used, the content will position alongside the `DatePickerTrigger`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `reference` | The reference (or anchor) element that is being referred to for positioning. If not provided will use the current component as anchor. | `ReferenceElement` | No | - | ### Calendar Contains all the parts of a calendar **Slots** | Name | Description | Type | | --- | --- | --- | | `date` | | `DateValue` | | `grid` | | `Grid[]` | | `weekDays` | | `string[]` | | `weekStartsOn` | | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | | `locale` | | `string` | | `fixedWeeks` | | `boolean` | ### Header Contains the navigation buttons and the heading segments. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Prev Button Calendar navigation button. It navigates the calendar one month/year/decade in the past based on the current calendar view. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `prevPage` | The function to be used for the prev page. Overwrites the prevPage function set on the CalendarRoot. | `((placeholder: DateValue) => DateValue)` | No | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `disabled` | Current disable state | `boolean` | ### Next Button Calendar navigation button. It navigates the calendar one month/year/decade in the future based on the current calendar view. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `nextPage` | The function to be used for the next page. Overwrites the nextPage function set on the CalendarRoot. | `((placeholder: DateValue) => DateValue)` | No | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `disabled` | Current disable state | `boolean` | ### Heading Heading for displaying the current month and year/ **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `headingValue` | Current month and year | `string` | ### Grid Container for wrapping the calendar grid. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Grid Head Container for wrapping the grid head. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Grid Body Container for wrapping the grid body. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Grid Row Container for wrapping the grid row. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Head Cell Container for wrapping the head cell. Used for displaying the week days. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Cell Container for wrapping the calendar cells. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `date` | The date value for the cell | `DateValue` | Yes | - | ### Cell Trigger Interactable container for displaying the cell dates. Clicking it selects the date. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `day` | The date value provided to the cell trigger | `DateValue` | Yes | - | | `month` | The month in which the cell is rendered | `DateValue` | Yes | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `dayValue` | Current day | `string` | | `disabled` | Current disable state | `boolean` | | `selected` | Current selected state | `boolean` | | `today` | Current today state | `boolean` | | `outsideView` | Current outside view state | `boolean` | | `outsideVisibleView` | Current outside visible view state | `boolean` | | `unavailable` | Current unavailable state | `boolean` | ## Accessibility ### Keyboard Interactions --- --- url: /docs/components/date-range-field.md description: Allows users to input a range of dates within a designated field. --- # Date Range Field Alpha ## Features ## Preface The component depends on the [@internationalized/date](https://react-spectrum.adobe.com/internationalized/date/index.html) package, which solves a lot of the problems that come with working with dates and times in JavaScript. We highly recommend reading through the documentation for the package to get a solid feel for how it works, and you'll need to install it in your project to use the date-related components. ## Installation Install the date package. Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Root Contains all the parts of a date field **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `defaultPlaceholder` | The default placeholder date | `DateValue` | No | - | | `defaultValue` | The default value for the calendar | `DateRange` | No | - | | `dir` | The reading direction of the date field when applicable. If omitted, inherits globally from ConfigProvider or assumes LTR (left-to-right) reading mode. | `"ltr" \| "rtl"` | No | - | | `disabled` | Whether or not the date field is disabled | `boolean` | No | `false` | | `granularity` | The granularity to use for formatting times. 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 | `"day" \| "hour" \| "minute" \| "second"` | No | - | | `hideTimeZone` | Whether or not to hide the time zone segment of the field | `boolean` | No | - | | `hourCycle` | The hour cycle used for formatting times. Defaults to the local preference | `12 \| 24` | No | - | | `id` | Id of the element | `string` | No | - | | `isDateUnavailable` | A function that returns whether or not a date is unavailable | `Matcher` | No | - | | `locale` | The locale to use for formatting dates | `string` | No | - | | `maxValue` | The maximum date that can be selected | `DateValue` | No | - | | `minValue` | The minimum date that can be selected | `DateValue` | No | - | | `modelValue` | The controlled value of the field. Can be bound as v-model. | `DateRange \| null` | No | - | | `name` | The name of the field. Submitted with its owning form as part of a name/value pair. | `string` | No | - | | `placeholder` | 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 view | `DateValue` | No | - | | `readonly` | Whether or not the date field is readonly | `boolean` | No | `false` | | `required` | When true, indicates that the user must set the value before the owning form can be submitted. | `boolean` | No | - | | `step` | The stepping interval for the time fields. Defaults to 1. | `DateStep` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `update:modelValue` | Event handler called whenever the model value changes | `[date: DateRange]` | | `update:placeholder` | Event handler called whenever the placeholder value changes | `[date: DateValue]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `modelValue` | The current date range of the field | `DateRange \| null` | | `segments` | The date field segment contents | `{ start: { part: SegmentPart; value: string; }[]; end: { part: SegmentPart; value: string; }[]; }` | | `isInvalid` | Value if the input is invalid | `boolean` | **Methods** | Name | Description | Type | | --- | --- | --- | | `setFocusedElement` | | `(el: HTMLElement) => void` | ### Input Contains the date field segments **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `part` | The part of the date to render | `"day" \| "month" \| "year" \| "hour" \| "minute" \| "second" \| "dayPeriod" \| "literal" \| "timeZoneName"` | Yes | - | | `type` | The type of field to render (start or end) | `"start" \| "end"` | Yes | - | ## Accessibility ### Keyboard Interactions --- --- url: /docs/components/date-range-picker.md description: >- Facilitates the selection of date ranges through an input and calendar-based interface. --- # Date Range Picker Alpha ## Features ## Preface The component depends on the [@internationalized/date](https://react-spectrum.adobe.com/internationalized/date/index.html) package, which solves a lot of the problems that come with working with dates and times in JavaScript. We highly recommend reading through the documentation for the package to get a solid feel for how it works, and you'll need to install it in your project to use the date-related components. ## Installation Install the date package. Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Root Contains all the parts of a date picker **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `allowNonContiguousRanges` | When combined with isDateUnavailable, determines whether non-contiguous ranges, i.e. ranges containing unavailable dates, may be selected. | `boolean` | No | `false` | | `closeOnSelect` | Whether or not to close the popover on range select | `boolean` | No | `false` | | `defaultOpen` | The open state of the popover when it is initially rendered. Use when you do not need to control its open state. | `boolean` | No | `false` | | `defaultPlaceholder` | The default placeholder date | `DateValue` | No | - | | `defaultValue` | The default value for the calendar | `DateRange` | No | `{ start: undefined, end: undefined }` | | `dir` | The reading direction of the date field when applicable. If omitted, inherits globally from ConfigProvider or assumes LTR (left-to-right) reading mode. | `"ltr" \| "rtl"` | No | - | | `disabled` | Whether or not the date field is disabled | `boolean` | No | `false` | | `fixedDate` | Which part of the range should be fixed | `"start" \| "end"` | No | - | | `fixedWeeks` | Whether or not to always display 6 weeks in the calendar | `boolean` | No | `false` | | `granularity` | The granularity to use for formatting times. 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 | `"day" \| "hour" \| "minute" \| "second"` | No | - | | `hideTimeZone` | Whether or not to hide the time zone segment of the field | `boolean` | No | - | | `hourCycle` | The hour cycle used for formatting times. Defaults to the local preference | `12 \| 24` | No | - | | `id` | Id of the element | `string` | No | - | | `isDateDisabled` | A function that returns whether or not a date is disabled | `Matcher` | No | - | | `isDateHighlightable` | A function that returns whether or not a date is hightable | `Matcher` | No | - | | `isDateUnavailable` | A function that returns whether or not a date is unavailable | `Matcher` | No | - | | `locale` | The locale to use for formatting dates | `string` | No | - | | `maximumDays` | The maximum number of days that can be selected in a range | `number` | No | - | | `maxValue` | The maximum date that can be selected | `DateValue` | No | - | | `minValue` | The minimum date that can be selected | `DateValue` | No | - | | `modal` | The modality of the popover. When set to true, interaction with outside elements will be disabled and only popover content will be visible to screen readers. | `boolean` | No | `false` | | `modelValue` | The controlled value of the field. Can be bound as v-model. | `DateRange \| null` | No | - | | `name` | The name of the field. Submitted with its owning form as part of a name/value pair. | `string` | No | - | | `numberOfMonths` | The number of months to display at once | `number` | No | `1` | | `open` | The controlled open state of the popover. | `boolean` | No | - | | `pagedNavigation` | This property causes the previous and next buttons to navigate by the number of months displayed at once, rather than one month | `boolean` | No | `false` | | `placeholder` | 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 view | `DateValue` | No | - | | `preventDeselect` | Whether or not to prevent the user from deselecting a date without selecting another date first | `boolean` | No | `false` | | `readonly` | Whether or not the date field is readonly | `boolean` | No | `false` | | `required` | When true, indicates that the user must set the value before the owning form can be submitted. | `boolean` | No | - | | `step` | The stepping interval for the time fields. Defaults to 1. | `DateStep` | No | - | | `weekdayFormat` | The format to use for the weekday strings provided via the weekdays slot prop | `"narrow" \| "short" \| "long"` | No | `"narrow"` | | `weekStartsOn` | The day of the week to start the calendar on | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `update:modelValue` | Event handler called whenever the model value changes | `[date: DateRange]` | | `update:open` | Event handler called when the open state of the submenu changes. | `[value: boolean]` | | `update:placeholder` | Event handler called whenever the placeholder value changes | `[date: DateValue]` | | `update:startValue` | Event handler called whenever the start value changes | `[date: DateValue]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `modelValue` | | `DateRange` | | `open` | | `boolean` | ### Field Contains the date picker date field segments and trigger **Slots** | Name | Description | Type | | --- | --- | --- | | `segments` | | `{ start: { part: SegmentPart; value: string; }[]; end: { part: SegmentPart; value: string; }[]; }` | | `modelValue` | | `DateRange \| null` | ### Input Contains the date picker date field segments **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `part` | The part of the date to render | `"day" \| "month" \| "year" \| "hour" \| "minute" \| "second" \| "dayPeriod" \| "literal" \| "timeZoneName"` | Yes | - | | `type` | The type of field to render (start or end) | `"start" \| "end"` | Yes | - | ### Trigger The button that toggles the popover. By default, the `DateRangePickerContent` will position itself against the trigger. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Content The component that pops out when the popover is open. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `align` | The preferred alignment against the trigger. May change when collisions occur. | `"start" \| "center" \| "end"` | No | - | | `alignFlip` | Flip alignment when colliding with boundary. May only occur when prioritizePosition is true. | `boolean` | No | - | | `alignOffset` | An offset in pixels from the start or end alignment options. | `number` | No | - | | `arrowPadding` | The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners. | `number` | No | - | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `avoidCollisions` | When true, overrides the side and align preferences to prevent collisions with boundary edges. | `boolean` | No | - | | `collisionBoundary` | The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. | `Element \| (Element \| null)[] \| null` | No | - | | `collisionPadding` | The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }. | `number \| Partial>` | No | - | | `dir` | The reading direction of the popper content when applicable. If omitted, inherits globally from ConfigProvider or assumes LTR (left-to-right) reading mode. | `"ltr" \| "rtl"` | No | - | | `disableOutsidePointerEvents` | When true, hover/focus/click interactions will be disabled on elements outside the DismissableLayer. Users will need to click twice on outside elements to interact with them: once to close the DismissableLayer, and again to trigger the element. | `boolean` | No | - | | `disableUpdateOnLayoutShift` | Whether to disable the update position for the content when the layout shifted. | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | | `hideShiftedArrow` | When true, hides the arrow when it cannot be centered to the reference element. | `boolean` | No | - | | `hideWhenDetached` | Whether to hide the content when the trigger becomes fully occluded. | `boolean` | No | - | | `memoDependencies` | Reactive dependencies that should invalidate the memoized content subtree. | `unknown[]` | No | - | | `portal` | Props to control the portal wrapped around the content. | `PopoverPortalProps` | No | - | | `positionStrategy` | The type of CSS position property to use. | `"fixed" \| "absolute"` | No | - | | `prioritizePosition` | Force content to be position within the viewport. Might overlap the reference element, which may not be desired. | `boolean` | No | - | | `reference` | The custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element. | `ReferenceElement` | No | - | | `side` | The preferred side of the trigger to render against when open. Will be reversed when collisions occur and avoidCollisions is enabled. | `"top" \| "right" \| "bottom" \| "left"` | No | - | | `sideFlip` | Flip to the opposite side when colliding with boundary. | `boolean` | No | - | | `sideOffset` | The distance in pixels from the trigger. | `number` | No | - | | `sticky` | 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. | `"partial" \| "always"` | No | - | | `updatePositionStrategy` | Strategy to update the position of the floating element on every animation frame. | `"always" \| "optimized"` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `closeAutoFocus` | Event handler called when auto-focusing on close. Can be prevented. | `[event: Event]` | | `escapeKeyDown` | Event handler called when the escape key is down. Can be prevented. | `[event: KeyboardEvent]` | | `focusOutside` | Event handler called when the focus moves outside of the DismissableLayer. Can be prevented. | `[event: FocusOutsideEvent]` | | `interactOutside` | Event handler called when an interaction happens outside the DismissableLayer. Specifically, when a pointerdown event happens outside or focus moves outside of it. Can be prevented. | `[event: PointerDownOutsideEvent \| FocusOutsideEvent]` | | `openAutoFocus` | Event handler called when auto-focusing on open. Can be prevented. | `[event: Event]` | | `pointerDownOutside` | Event handler called when a pointerdown event happens outside of the DismissableLayer. Can be prevented. | `[event: PointerDownOutsideEvent]` | ### Arrow An optional arrow element to render alongside the popover. This can be used to help visually link the anchor with the `DateRangePickerContent`. Must be rendered inside `DateRangePickerContent`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `height` | The height of the arrow in pixels. | `number` | No | - | | `rounded` | When true, render the rounded version of arrow. Do not work with as/asChild | `boolean` | No | - | | `width` | The width of the arrow in pixels. | `number` | No | - | ### Close The button that closes an open date picker. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Anchor An optional element to position the `DateRangePickerContent` against. If this part is not used, the content will position alongside the `DateRangePickerTrigger`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `reference` | The reference (or anchor) element that is being referred to for positioning. If not provided will use the current component as anchor. | `ReferenceElement` | No | - | ### Calendar Contains all the parts of a calendar **Slots** | Name | Description | Type | | --- | --- | --- | | `date` | | `DateValue` | | `grid` | | `Grid[]` | | `weekDays` | | `string[]` | | `weekStartsOn` | | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | | `locale` | | `string` | | `fixedWeeks` | | `boolean` | ### Header Contains the navigation buttons and the heading segments. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Prev Button Calendar navigation button. It navigates the calendar one month/year/decade in the past based on the current calendar view. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `prevPage` | The function to be used for the prev page. Overwrites the prevPage function set on the RangeCalendarRoot. | `((placeholder: DateValue) => DateValue)` | No | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `disabled` | Current disable state | `boolean` | ### Next Button Calendar navigation button. It navigates the calendar one month/year/decade in the future based on the current calendar view. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `nextPage` | The function to be used for the next page. Overwrites the nextPage function set on the RangeCalendarRoot. | `((placeholder: DateValue) => DateValue)` | No | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `disabled` | Current disable state | `boolean` | ### Heading Heading for displaying the current month and year **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `headingValue` | Current month and year | `string` | ### Grid Container for wrapping the calendar grid. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Grid Head Container for wrapping the grid head. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Grid Body Container for wrapping the grid body. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Grid Row Container for wrapping the grid row. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Head Cell Container for wrapping the head cell. Used for displaying the week days. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Cell Container for wrapping the calendar cells. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `date` | | `DateValue` | Yes | - | ### Cell Trigger Interactable container for displaying the cell dates. Clicking it selects the date. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `day` | | `DateValue` | Yes | - | | `month` | | `DateValue` | Yes | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `dayValue` | Current day | `string` | | `disabled` | Current disable state | `boolean` | | `selected` | Current selected state | `boolean` | | `today` | Current today state | `boolean` | | `outsideView` | Current outside view state | `boolean` | | `outsideVisibleView` | Current outside visible view state | `boolean` | | `unavailable` | Current unavailable state | `boolean` | | `highlighted` | Current highlighted state | `boolean` | | `highlightedStart` | Current highlighted start state | `boolean` | | `highlightedEnd` | Current highlighted end state | `boolean` | | `selectionStart` | Current selection start state | `boolean` | | `selectionEnd` | Current selection end state | `boolean` | ## Accessibility ### Keyboard Interactions --- --- url: /docs/guides/dates.md description: How to work with dates and times in Reka UI. --- # Dates & Times The inner-workings of our date-related components are heavily inspired by the research and work done by the [React Aria](https://react-spectrum.adobe.com/react-aria/) team at Adobe, who have created robust date components that excel in terms of accessibility, user experience, and flexibility. The component depends on the [@internationalized/date](https://react-spectrum.adobe.com/internationalized/date/index.html) package, which solves a lot of the problems that come with working with dates and times in JavaScript. We highly recommend reading through the documentation for the package to get a solid feel for how it works, and you'll need to install it in your project to use the date-related components. ## Date Objects We use the `DateValue` objects provided by `@internationalized/date` to represent dates in the various components. These objects are immutable, and provide information about the type of date they represent: * `CalendarDate`: A date with no time component, such as `2023-10-11`. * `CalendarDateTime`: A date with a time component, but without a timezone, such as `2023-10-11T12:30:00`. * `ZonedDateTime`: A date with a time component and a timezone, such as `2023-10-11T21:00:00:00-04:00[America/New_York]`. The benefit of using these objects is that we can be very specific about the type of date we want, and the behavior of the builder will adapt to that type. Additionally, you don't have to worry about wrangling timezones, daylight savings time, or any other date-related nuance. ## Utility Functions This package also provides a number of utility functions which solves a lot of the problems that come with working with dates and times in JavaScript. Specially designed to work well with [@internationalized/date](https://react-spectrum.adobe.com/internationalized/date/index.html). # DateValue Types ## CalendarDate Represents a date without any time component. This is ideal for dates like birthdays, anniversaries, or deadlines where only the date matters. ```ts // Creating a CalendarDate import { CalendarDate, getLocalTimeZone, parseDate, today } from '@internationalized/date' // From year, month, day parameters const date = new CalendarDate(2024, 7, 10) // From ISO 8601 string const parsedDate = parseDate('2024-07-10') // Current date in specific timezone const losAngelesToday = today('America/Los_Angeles') // Current date in user's timezone const localToday = today(getLocalTimeZone()) ``` See the [CalendarDate API Documentation](https://react-spectrum.adobe.com/internationalized/date/CalendarDate.html) for additional methods. ## CalendarDateTime Represents a date with a time component, but without timezone information. This is useful for events that have a specific time but are not tied to a particular timezone, such as local appointments. ```ts // Creating a CalendarDateTime import { CalendarDateTime, parseDateTime } from '@internationalized/date' // From date and time components const dateTime = new CalendarDateTime(2024, 7, 10, 12, 30, 0) // From ISO 8601 string const parsedDateTime = parseDateTime('2024-07-10T12:30:00') ``` See the [CalendarDateTime API Documentation](https://react-spectrum.adobe.com/internationalized/date/CalendarDateTime.html) for additional methods. ## ZonedDateTime Represents a specific date and time in a specific timezone. This is crucial for events that occur at an exact moment regardless of the user's location, such as conferences, live broadcasts, or international meetings. ```ts // Creating a ZonedDateTime import { parseAbsolute, parseAbsoluteToLocal, parseZonedDateTime, ZonedDateTime, } from '@internationalized/date' const date = new ZonedDateTime( 2024, // year 7, // month 10, // day 'America/Los_Angeles', // timezone -25200000, // UTC offset in milliseconds (PDT) 12, // hour 30, // minute 0 // second ) // From ISO 8601 strings using different parsing functions const date1 = parseZonedDateTime('2024-07-12T00:45[America/New_York]') const date2 = parseAbsolute('2024-07-12T07:45:00Z', 'America/New_York') const date3 = parseAbsoluteToLocal('2024-07-12T07:45:00Z') ``` See the [ZonedDateTime](https://react-spectrum.adobe.com/internationalized/date/ZonedDateTime.html) API documentation for more information. ## Updating DateValue Objects Since DateValue objects are immutable, you must create new instances when updating them. Here are the correct ways to modify them: ```ts // INCORRECT - will not work let placeholder = new CalendarDate(2024, 7, 10) placeholder.month = 8 // Error! DateValue objects are immutable // CORRECT - using methods that return new instances let placeholder = new CalendarDate(2024, 7, 10) // Method 1: Using set() to change specific properties placeholder = placeholder.set({ month: 8 }) // Method 2: Using add() to increment values placeholder = placeholder.add({ months: 1 }) // Method 3: Using subtract() to decrement values placeholder = placeholder.subtract({ days: 5 }) // Method 4: Using cycle() to cycle through valid values placeholder = placeholder.cycle('month', 'forward', [1, 3, 5, 7, 9, 11]) ``` ## Parsing ### Parsing Date Strings When working with date strings from APIs or databases, use the appropriate parsing function based on the type of DateValue you need: ```ts import { parseAbsolute, // For ZonedDateTime from UTC string + timezone parseAbsoluteToLocal, // For ZonedDateTime in local timezone parseDate, // For CalendarDate parseDateTime, // For CalendarDateTime parseZonedDateTime, // For ZonedDateTime with timezone name } from '@internationalized/date' // Examples const date = parseDate('2024-07-10') // CalendarDate const dateTime = parseDateTime('2024-07-10T12:30:00') // CalendarDateTime const zonedDate = parseZonedDateTime('2024-07-12T00:45[America/New_York]') // ZonedDateTime const absoluteDate = parseAbsolute('2024-07-12T07:45:00Z', 'America/New_York') // ZonedDateTime const localDate = parseAbsoluteToLocal('2024-07-12T07:45:00Z') // ZonedDateTime in user's timezone ``` ## Common Gotchas and Tips * **Month Indexing**: Unlike JavaScript's Date object (which is 0-indexed), @internationalized/date uses 1-indexed months (January = 1). * **Immutability**: Always reassign when modifying date objects: `date = date.add({ days: 1 })`. * **Timezone Handling**: Use `ZonedDateTime` for schedule-critical events like meetings or appointments. * **Type Consistency**: Match your DateValue types to your needs - if you need time selection, use `CalendarDateTime` instead of `CalendarDate`. * **Parsing Functions**: Choose the right parsing function to avoid unexpected results. For example, use `parseDate` for date-only strings and `parseDateTime` for date-time strings without timezone. ### How to use? ```ts import type { DateValue } from '@internationalized/date' import { CalendarDate } from '@internationalized/date' import { createDateRange, createDecade, createMonth, createYear, createYearRange, getDaysInMonth, getWeekNumber, hasTime, isAfter, isAfterOrSame, isBefore, isBeforeOrSame, isBetween, isBetweenInclusive, isCalendarDateTime, isZonedDateTime, parseStringToDateValue, toDate, } from 'reka-ui/date' const date = new CalendarDate(1995, 8, 18) const minDate = new CalendarDate(1995, 8, 1) const maxDate = new CalendarDate(1995, 8, 31) parseStringToDateValue('1995-08-18', date) // returns a DateValue object toDate(date) // returns a Date object isCalendarDateTime(date) // returns false isZonedDateTime(date) // returns false hasTime(date) // returns false getDaysInMonth(date) // returns 31 getWeekNumber(new CalendarDate(1995, 8, 18), 'en-US', 'sun') // returns 33 isAfter(date, minDate) // returns true isBeforeOrSame(date, maxDate) // returns true isAfterOrSame(date, minDate) // returns true isBefore(date, maxDate) // returns true isBetweenInclusive(date, minDate, maxDate) // returns true isBetween(date, minDate, maxDate) // returns true createMonth({ dateObj: new CalendarDate(1995, 8, 18), weekStartsOn: 0, locale: 'en', fixedWeeks: true }) // returns a grid of days as DateValue for the month, also containing the dateObj, plus an array of days for the month createYear({ dateObj: new CalendarDate(1995, 8, 18), numberOfMonths: 2, pagedNavigation: true }) // returns an array of months as DateValue, centered around the dateObj taking into account the numberOfMonths and pagedNavigation when returning the months createDecade({ dateObj: new CalendarDate(1995, 8, 18), startIndex: -10, endIndex: 10 }) // returns a decade centered around the dateObj createDateRange({ start: new CalendarDate(1995, 8, 18), end: new CalendarDate(2005, 8, 18) }) // returns an array of dates as DateValue between the start and end date createYearRange({ start: new CalendarDate(1995, 8, 18), end: new CalendarDate(2005, 8, 18) }) // returns an array of years as DateValue between the start and end date ``` --- --- url: /docs/components/dialog.md description: >- A window overlaid on either the primary window or another dialog window, rendering the content underneath inert. --- # Dialog ## Features ## Installation Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Root Contains all the parts of a dialog **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `defaultOpen` | The open state of the dialog when it is initially rendered. Use when you do not need to control its open state. | `boolean` | No | `false` | | `modal` | The modality of the dialog When set to true, interaction with outside elements will be disabled and only dialog content will be visible to screen readers. | `boolean` | No | `true` | | `open` | The controlled open state of the dialog. Can be binded as v-model:open. | `boolean` | No | - | | `unmountOnHide` | When set to false, the dialog content will not be unmounted when closed, but instead hidden with CSS. Useful for SEO or when you want to improve performance by not remounting the component on every open. | `boolean` | No | `true` | **Events** | Name | Description | Type | | --- | --- | --- | | `update:open` | Event handler called when the open state of the dialog changes. | `[value: boolean]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `open` | Current open state | `boolean` | | `close` | Close the dialog | `(): void` | ### Trigger The button that opens the dialog **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Portal When used, portals your overlay and content parts into the `body`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `defer` | Defer the resolving of a Teleport target until other parts of the application have mounted (requires Vue 3.5.0+) reference | `boolean` | No | - | | `disabled` | Disable teleport and render the component inline reference | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | | `to` | Vue native teleport component prop :to reference | `string \| HTMLElement` | No | - | ### Overlay A layer that covers the inert portion of the view when the dialog is open. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | ### Content Contains content to be rendered in the open dialog **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disableOutsidePointerEvents` | When true, hover/focus/click interactions will be disabled on elements outside the DismissableLayer. Users will need to click twice on outside elements to interact with them: once to close the DismissableLayer, and again to trigger the element. | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `closeAutoFocus` | Event handler called when auto-focusing on close. Can be prevented. | `[event: Event]` | | `escapeKeyDown` | Event handler called when the escape key is down. Can be prevented. | `[event: KeyboardEvent]` | | `focusOutside` | Event handler called when the focus moves outside of the DismissableLayer. Can be prevented. | `[event: FocusOutsideEvent]` | | `interactOutside` | Event handler called when an interaction happens outside the DismissableLayer. Specifically, when a pointerdown event happens outside or focus moves outside of it. Can be prevented. | `[event: PointerDownOutsideEvent \| FocusOutsideEvent]` | | `openAutoFocus` | Event handler called when auto-focusing on open. Can be prevented. | `[event: Event]` | | `pointerDownOutside` | Event handler called when a pointerdown event happens outside of the DismissableLayer. Can be prevented. | `[event: PointerDownOutsideEvent]` | ### Close The button that closes the dialog **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Title An accessible title to be announced when the dialog is opened. If you want to hide the title, wrap it inside our Visually Hidden utility like this ``. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"h2"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Description An optional accessible description to be announced when the dialog is opened. If you want to hide the description, wrap it inside our Visually Hidden utility like this ``. If you want to remove the description entirely, remove this part and pass `:aria-describedby="undefined"` to `DialogContent`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"p"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ## Examples ### Nested dialog You can nest multiple layers of dialogs. ### Close after asynchronous form submission Use the controlled props to programmatically close the Dialog after an async operation has completed. ```vue line=4,5,15-19,22-24 ``` ### Scrollable overlay Move the content inside the overlay to render a dialog with overflow. ```vue // index.vue ``` ```css /* styles.css */ .DialogOverlay { background: rgba(0 0 0 / 0.5); position: fixed; top: 0; left: 0; right: 0; bottom: 0; display: grid; place-items: center; overflow-y: auto; } .DialogContent { min-width: 300px; background: white; padding: 30px; border-radius: 4px; } ``` However, there's a caveat to this approach, where user might click on the scrollbar and close the dialog unintentionally. There's no universal solution that would fix this issue for now, however you can add the following snippet to `DialogContent` to prevent closing of modal when clicking on scrollbar. ```vue ``` ### Custom portal container Customise the element that your dialog portals into. ```vue line=4,11,17 ``` ### Disable close on Interaction outside For example, if you have some global Toaster component that should not close the Dialog when clicking on it. ## Accessibility Adheres to the [Dialog WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/). ### Close icon button When providing an icon (or font icon), remember to label it correctly for screen reader users. ```vue line=9-11 ``` ### Close using slot props Alternatively, you can use the `close` method provided by the `DialogRoot` slot props to programmatically close the dialog. ```vue line=4,8,16-20 ``` ### Keyboard Interactions ## Custom APIs Create your own API by abstracting the primitive parts into your own component. ### Abstract the overlay and the close button This example abstracts the `DialogOverlay` and `DialogClose` parts. #### Usage ```vue ``` #### Implementation ```ts // your-dialog.ts export { default as DialogContent } from 'DialogContent.vue' export { DialogRoot as Dialog, DialogTrigger } from 'reka-ui' ``` ```vue ``` --- --- url: /docs/components/drawer.md description: >- A panel that slides in from the edge of the screen, with support for swipe-to-dismiss, snap points, and nested drawers. --- # Drawer Alpha ## Features ## Installation Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## Animating the drawer The Drawer is unstyled, so the enter/exit transitions and the swipe gesture are driven entirely by your CSS. `DrawerContent` exposes the drag offset through CSS custom properties so you can wire up the live transform: * `--drawer-swipe-movement-y` — vertical drag offset (for top/bottom drawers) * `--drawer-swipe-movement-x` — horizontal drag offset (for left/right drawers) * `--drawer-snap-point-offset` — offset of the active snap point, when snap points are used * `--drawer-swipe-progress` — `0` at rest, approaching `1` as the drawer is swiped away ```css .DrawerContent { /* Follow the pointer while dragging. */ transform: translateY(var(--drawer-swipe-movement-y, 0px)); transition: transform 450ms cubic-bezier(0.32, 0.72, 0, 1); } /* Use the independent `translate` property for the enter/exit keyframes so they compose with the `transform` above instead of clobbering the drag offset. */ .DrawerContent[data-state='open'] { animation: slideIn 450ms cubic-bezier(0.32, 0.72, 0, 1); } .DrawerContent[data-state='closed'] { animation: slideOut 450ms cubic-bezier(0.32, 0.72, 0, 1); } /* Cut the transition while actively dragging so the drawer tracks the pointer. */ .DrawerContent[data-swiping] { transition-duration: 0ms; } @keyframes slideIn { from { translate: 0 100%; } } @keyframes slideOut { to { translate: 0 100%; } } ``` ## API Reference ### Root Contains all the parts of a drawer. Manages open state, modality, swipe direction and snap points, and provides the context consumed by every other part. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `defaultOpen` | | `boolean` | No | `false` | | `defaultSnapPoint` | | `null \| string \| number` | No | - | | `modal` | Modality of the drawer. true (default): modal with focus trap, scroll lock, and outside-press dismiss 'trap-focus': traps focus but allows outside pointer events (non-modal side panels) false: non-modal | `false \| true \| "trap-focus"` | No | `true` | | `open` | v-model:open | `boolean` | No | - | | `snapPoint` | v-model:snapPoint | `null \| string \| number` | No | - | | `snapPoints` | Preset snap positions (fractions 0-1, pixels >1, or '148px'/'30rem' strings) | `DrawerSnapPoint[]` | No | - | | `snapToSequentialPoints` | When true, snaps to the next sequential snap point (one step at a time). When false, snaps to the nearest snap point by distance. | `boolean` | No | `false` | | `swipeDirection` | Direction to swipe to dismiss. | `"right" \| "left" \| "down" \| "up"` | No | `"down"` | **Events** | Name | Description | Type | | --- | --- | --- | | `update:open` | Event handler called when the open state of the dialog changes. | `[value: boolean, details?: DrawerOpenChangeDetails]` | | `update:openComplete` | | `[value: boolean]` | | `update:snapPoint` | | `[value: DrawerSnapPoint \| null]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `open` | | `boolean` | | `close` | | `(): void` | ### Trigger The button that opens the drawer. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Portal When used, portals your overlay and content parts into the `body`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `defer` | Defer the resolving of a Teleport target until other parts of the application have mounted (requires Vue 3.5.0+) reference | `boolean` | No | - | | `disabled` | Disable teleport and render the component inline reference | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | | `to` | Vue native teleport component prop :to reference | `string \| HTMLElement` | No | - | ### Overlay A layer that covers the inert portion of the view when the drawer is open. Only rendered when the drawer is `modal`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `forceMount` | Keep mounted for animation control. | `boolean` | No | `false` | | `forceRender` | Render even when inside a nested drawer. | `boolean` | No | `false` | ### Content Contains the content to be rendered in the open drawer. Owns the swipe gesture and exposes the drag offset through CSS custom properties (see [Animating the drawer](#animating-the-drawer)). Also aliased as `DrawerPopup` for Base UI parity. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disableOutsidePointerEvents` | When true, hover/focus/click interactions will be disabled on elements outside the DismissableLayer. Users will need to click twice on outside elements to interact with them: once to close the DismissableLayer, and again to trigger the element. | `boolean` | No | - | | `finalFocus` | Final focus target when the drawer closes. true / default: focus the trigger false: do not restore focus element ref: focus that specific element | `boolean \| HTMLElement \| null` | No | - | | `forceMount` | | `boolean` | No | - | | `initialFocus` | Initial focus target when the drawer opens. true / default: focus the first focusable element inside false: do not focus anything element ref: focus that specific element | `boolean \| HTMLElement \| null` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `closeAutoFocus` | Event handler called when auto-focusing on close. Can be prevented. | `[event: Event]` | | `escapeKeyDown` | Event handler called when the escape key is down. Can be prevented. | `[event: KeyboardEvent]` | | `focusOutside` | Event handler called when the focus moves outside of the DismissableLayer. Can be prevented. | `[event: FocusOutsideEvent]` | | `interactOutside` | Event handler called when an interaction happens outside the DismissableLayer. Specifically, when a pointerdown event happens outside or focus moves outside of it. Can be prevented. | `[event: PointerDownOutsideEvent \| FocusOutsideEvent]` | | `openAutoFocus` | Event handler called when auto-focusing on open. Can be prevented. | `[event: Event]` | | `pointerDownOutside` | Event handler called when a pointerdown event happens outside of the DismissableLayer. Can be prevented. | `[event: PointerDownOutsideEvent]` | ### Close The button that closes the drawer. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Title An accessible title to be announced when the drawer is opened. If you want to hide the title, wrap it inside our Visually Hidden utility like this ``. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"h2"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Description An optional accessible description to be announced when the drawer is opened. If you want to hide the description, wrap it inside our Visually Hidden utility like this ``. If you want to remove the description entirely, remove this part and pass `:aria-describedby="undefined"` to `DrawerContent`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"p"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Handle A visual grab handle that hints the drawer can be dragged. It is purely decorative (`aria-hidden`) — the whole content is draggable regardless. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### SwipeArea An off-screen edge area that lets users swipe the drawer **open**. By default it listens on the opposite side of the Root's `swipeDirection`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | Disable swipe-to-open. | `boolean` | No | `false` | | `swipeDirection` | Override the open swipe direction (defaults to opposite of Root's swipeDirection). | `"right" \| "left" \| "down" \| "up"` | No | - | ### Viewport An optional scrollable wrapper for the drawer content. Mirrors Base UI's `Drawer.Viewport` and carries a `data-drawer-viewport` attribute for downstream selectors. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Indent Wraps page content that should visually shift (scale/indent) as the drawer is swiped, mimicking the native iOS "card stack" effect. Reads the visual state from a parent `DrawerProvider` and syncs the `--drawer-swipe-progress` and `--drawer-height` CSS variables onto its element. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### IndentBackground The backdrop layer revealed behind an indented page (typically a solid colour that peeks out as the page scales down). Companion to `Indent`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ## Examples ### Choosing a side `DrawerRoot` slides up from the bottom by default. Set `swipeDirection` to change the edge the drawer attaches to and the direction users swipe to dismiss it. ```vue line=2 ``` ```css /* A right-anchored drawer slides along the X axis instead. */ .DrawerContent { position: fixed; inset-block: 0; right: 0; width: 20rem; transform: translateX(var(--drawer-swipe-movement-x, 0px)); transition: transform 450ms cubic-bezier(0.32, 0.72, 0, 1); } .DrawerContent[data-state='open'] { animation: slideInRight 450ms cubic-bezier(0.32, 0.72, 0, 1); } .DrawerContent[data-state='closed'] { animation: slideOutRight 450ms cubic-bezier(0.32, 0.72, 0, 1); } .DrawerContent[data-swiping] { transition-duration: 0ms; } @keyframes slideInRight { from { translate: 100% 0; } } @keyframes slideOutRight { to { translate: 100% 0; } } ``` ### Snap points Provide `snapPoints` to give the drawer intermediate resting positions. Each point is a fraction (`0`–`1`), a pixel value (`> 1`), or a string like `'148px'` / `'30rem'`. Use `v-model:snapPoint` to read or control the active one. ```vue line=5-9 ``` ### Non-modal drawer By default the drawer is `modal`: it traps focus, locks scroll, and dismisses on outside press. Set `modal` to `'trap-focus'` to keep the focus trap while still allowing interaction with the rest of the page (no overlay is rendered), or to `false` for a fully non-modal panel. ```vue line=2 ``` ### Reacting to why the drawer closed The `update:open` event carries a `details` object whose `reason` tells you what triggered the change — useful for distinguishing a deliberate close from a swipe. ```vue line=4-9 ``` Possible reasons are `swipe`, `escape-key`, `outside-press`, `click`, `cancel`, `trigger-press` and `close-press`. ### Close using slot props `DrawerRoot` exposes `open` and `close` via its default slot, so you can close the drawer programmatically from anywhere inside it. ```vue line=2 ``` ## Accessibility Adheres to the [Dialog WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/). ### Keyboard Interactions ## Custom APIs Create your own API by abstracting the primitive parts into your own component. ### Abstract the overlay and the portal This example abstracts the `DrawerPortal` and `DrawerOverlay` parts. #### Usage ```vue ``` #### Implementation ```ts // your-drawer.ts export { default as DrawerContent } from 'DrawerContent.vue' export { DrawerRoot as Drawer, DrawerTrigger } from 'reka-ui' ``` ```vue ``` --- --- url: /docs/components/dropdown-menu.md description: >- Displays a menu to the user—such as a set of actions or functions—triggered by a button. --- # DropdownMenu ## Features ## Installation Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Root Contains all the parts of a dropdown menu. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `defaultOpen` | The open state of the dropdown menu when it is initially rendered. Use when you do not need to control its open state. | `boolean` | No | - | | `dir` | The reading direction of the combobox when applicable. If omitted, inherits globally from ConfigProvider or assumes LTR (left-to-right) reading mode. | `"ltr" \| "rtl"` | No | - | | `modal` | The modality of the dropdown menu. When set to true, interaction with outside elements will be disabled and only menu content will be visible to screen readers. | `boolean` | No | `true` | | `open` | The controlled open state of the menu. Can be used as v-model:open. | `boolean` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `update:open` | Event handler called when the open state of the submenu changes. | `[payload: boolean]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `open` | Current open state | `boolean` | ### Trigger The button that toggles the dropdown menu. By default, the `DropdownMenuContent` will position itself against the trigger. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | When true, prevents the user from interacting with item | `boolean` | No | - | ### Portal When used, portals the content part into the `body`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `defer` | Defer the resolving of a Teleport target until other parts of the application have mounted (requires Vue 3.5.0+) reference | `boolean` | No | - | | `disabled` | Disable teleport and render the component inline reference | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | | `to` | Vue native teleport component prop :to reference | `string \| HTMLElement` | No | - | ### Content The component that pops out when the dropdown menu is open. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `align` | The preferred alignment against the trigger. May change when collisions occur. | `"start" \| "center" \| "end"` | No | - | | `alignFlip` | Flip alignment when colliding with boundary. May only occur when prioritizePosition is true. | `boolean` | No | - | | `alignOffset` | An offset in pixels from the start or end alignment options. | `number` | No | - | | `arrowPadding` | The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners. | `number` | No | - | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `avoidCollisions` | When true, overrides the side and align preferences to prevent collisions with boundary edges. | `boolean` | No | - | | `collisionBoundary` | The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. | `Element \| (Element \| null)[] \| null` | No | - | | `collisionPadding` | The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }. | `number \| Partial>` | No | - | | `disableUpdateOnLayoutShift` | Whether to disable the update position for the content when the layout shifted. | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | | `hideShiftedArrow` | When true, hides the arrow when it cannot be centered to the reference element. | `boolean` | No | - | | `hideWhenDetached` | Whether to hide the content when the trigger becomes fully occluded. | `boolean` | No | - | | `loop` | When true, keyboard navigation will loop from last item to first, and vice versa. | `boolean` | No | - | | `memoDependencies` | Reactive dependencies that should invalidate the memoized content subtree. | `unknown[]` | No | - | | `positionStrategy` | The type of CSS position property to use. | `"fixed" \| "absolute"` | No | - | | `prioritizePosition` | Force content to be position within the viewport. Might overlap the reference element, which may not be desired. | `boolean` | No | - | | `reference` | The custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element. | `ReferenceElement` | No | - | | `side` | The preferred side of the trigger to render against when open. Will be reversed when collisions occur and avoidCollisions is enabled. | `"top" \| "right" \| "bottom" \| "left"` | No | - | | `sideFlip` | Flip to the opposite side when colliding with boundary. | `boolean` | No | - | | `sideOffset` | The distance in pixels from the trigger. | `number` | No | - | | `sticky` | 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. | `"partial" \| "always"` | No | - | | `updatePositionStrategy` | Strategy to update the position of the floating element on every animation frame. | `"always" \| "optimized"` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `closeAutoFocus` | Event handler called when auto-focusing on close. Can be prevented. | `[event: Event]` | | `escapeKeyDown` | Event handler called when the escape key is down. Can be prevented. | `[event: KeyboardEvent]` | | `focusOutside` | Event handler called when the focus moves outside of the DismissableLayer. Can be prevented. | `[event: FocusOutsideEvent]` | | `interactOutside` | Event handler called when an interaction happens outside the DismissableLayer. Specifically, when a pointerdown event happens outside or focus moves outside of it. Can be prevented. | `[event: PointerDownOutsideEvent \| FocusOutsideEvent]` | | `pointerDownOutside` | Event handler called when a pointerdown event happens outside of the DismissableLayer. Can be prevented. | `[event: PointerDownOutsideEvent]` | ### Arrow An optional arrow element to render alongside the dropdown menu. This can be used to help visually link the trigger with the `DropdownMenuContent`. Must be rendered inside `DropdownMenuContent`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"svg"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `height` | The height of the arrow in pixels. | `number` | No | `5` | | `rounded` | When true, render the rounded version of arrow. Do not work with as/asChild | `boolean` | No | - | | `width` | The width of the arrow in pixels. | `number` | No | `10` | ### Item The component that contains the dropdown menu items. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | When true, prevents the user from interacting with the item. | `boolean` | No | - | | `textValue` | Optional text used for typeahead purposes. By default the typeahead behavior will use the .textContent of the item. Use this when the content is complex, or you have non-textual content inside. | `string` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `select` | Event handler called when the user selects an item (via mouse or keyboard). Calling event.preventDefault in this handler will prevent the menu from closing when selecting that item. | `[event: Event]` | ### Group Used to group multiple `DropdownMenuItem`s. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Label Used to render a label. It won't be focusable using arrow keys. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### CheckboxItem An item that can be controlled and rendered like a checkbox. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | When true, prevents the user from interacting with the item. | `boolean` | No | - | | `modelValue` | The controlled checked state of the item. Can be used as v-model. | `false \| true \| "indeterminate"` | No | - | | `textValue` | Optional text used for typeahead purposes. By default the typeahead behavior will use the .textContent of the item. Use this when the content is complex, or you have non-textual content inside. | `string` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `select` | Event handler called when the user selects an item (via mouse or keyboard). Calling event.preventDefault in this handler will prevent the menu from closing when selecting that item. | `[event: Event]` | | `update:modelValue` | Event handler called when the value changes. | `[payload: boolean]` | ### RadioGroup Used to group multiple `DropdownMenuRadioItem`s. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `modelValue` | The value of the selected item in the group. | `AcceptableValue` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `update:modelValue` | Event handler called when the value changes. | `[payload: AcceptableValue]` | ### RadioItem An item that can be controlled and rendered like a radio. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | When true, prevents the user from interacting with the item. | `boolean` | No | - | | `textValue` | Optional text used for typeahead purposes. By default the typeahead behavior will use the .textContent of the item. Use this when the content is complex, or you have non-textual content inside. | `string` | No | - | | `value` | The unique value of the item. | `AcceptableValue` | Yes | - | **Events** | Name | Description | Type | | --- | --- | --- | | `select` | Event handler called when the user selects an item (via mouse or keyboard). Calling event.preventDefault in this handler will prevent the menu from closing when selecting that item. | `[event: Event]` | ### ItemIndicator Renders when the parent `DropdownMenuCheckboxItem` or `DropdownMenuRadioItem` is checked. You can style this element directly, or you can use it as a wrapper to put an icon into, or both. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | ### Separator Used to visually separate items in the dropdown menu. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Sub Contains all the parts of a submenu. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `defaultOpen` | The open state of the dropdown menu when it is initially rendered. Use when you do not need to control its open state. | `boolean` | No | - | | `open` | The controlled open state of the menu. Can be used as v-model:open. | `boolean` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `update:open` | Event handler called when the open state of the submenu changes. | `[payload: boolean]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `open` | Current open state | `boolean` | ### SubTrigger An item that opens a submenu. Must be rendered inside `DropdownMenuSub`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | When true, prevents the user from interacting with the item. | `boolean` | No | - | | `textValue` | Optional text used for typeahead purposes. By default the typeahead behavior will use the .textContent of the item. Use this when the content is complex, or you have non-textual content inside. | `string` | No | - | ### SubContent The component that pops out when a submenu is open. Must be rendered inside `DropdownMenuSub`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `alignFlip` | Flip alignment when colliding with boundary. May only occur when prioritizePosition is true. | `boolean` | No | - | | `alignOffset` | An offset in pixels from the start or end alignment options. | `number` | No | - | | `arrowPadding` | The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners. | `number` | No | - | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `avoidCollisions` | When true, overrides the side and align preferences to prevent collisions with boundary edges. | `boolean` | No | - | | `collisionBoundary` | The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. | `Element \| (Element \| null)[] \| null` | No | - | | `collisionPadding` | The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }. | `number \| Partial>` | No | - | | `disableUpdateOnLayoutShift` | Whether to disable the update position for the content when the layout shifted. | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | | `hideShiftedArrow` | When true, hides the arrow when it cannot be centered to the reference element. | `boolean` | No | - | | `hideWhenDetached` | Whether to hide the content when the trigger becomes fully occluded. | `boolean` | No | - | | `loop` | When true, keyboard navigation will loop from last item to first, and vice versa. | `boolean` | No | - | | `memoDependencies` | Reactive dependencies that should invalidate the memoized content subtree. | `unknown[]` | No | - | | `positionStrategy` | The type of CSS position property to use. | `"fixed" \| "absolute"` | No | - | | `prioritizePosition` | Force content to be position within the viewport. Might overlap the reference element, which may not be desired. | `boolean` | No | - | | `reference` | The custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element. | `ReferenceElement` | No | - | | `sideFlip` | Flip to the opposite side when colliding with boundary. | `boolean` | No | - | | `sideOffset` | The distance in pixels from the trigger. | `number` | No | - | | `sticky` | 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. | `"partial" \| "always"` | No | - | | `updatePositionStrategy` | Strategy to update the position of the floating element on every animation frame. | `"always" \| "optimized"` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `closeAutoFocus` | Event handler called when auto-focusing on close. Can be prevented. | `[event: Event]` | | `entryFocus` | Event handler called when container is being focused. Can be prevented. | `[event: Event]` | | `escapeKeyDown` | Event handler called when the escape key is down. Can be prevented. | `[event: KeyboardEvent]` | | `focusOutside` | Event handler called when the focus moves outside of the DismissableLayer. Can be prevented. | `[event: FocusOutsideEvent]` | | `interactOutside` | Event handler called when an interaction happens outside the DismissableLayer. Specifically, when a pointerdown event happens outside or focus moves outside of it. Can be prevented. | `[event: PointerDownOutsideEvent \| FocusOutsideEvent]` | | `openAutoFocus` | Event handler called when auto-focusing on open. Can be prevented. | `[event: Event]` | | `pointerDownOutside` | Event handler called when a pointerdown event happens outside of the DismissableLayer. Can be prevented. | `[event: PointerDownOutsideEvent]` | ## Examples ### With submenus You can create submenus by using `DropdownMenuSub` in combination with its parts. ```vue line=9-11,24-33 ``` ### With disabled items You can add special styles to disabled items via the `data-disabled` attribute. ```vue line=18 ``` ```css line=2 /* styles.css */ .DropdownMenuItem[data-disabled] { color: gainsboro; } ``` ### With separators Use the `Separator` part to add a separator between items. ```vue line=7,18,20 ``` ### With labels Use the `Label` part to help label a section. ```vue line=5,17 ``` ### With checkbox items Use the `CheckboxItem` part to add an item that can be checked. ```vue line=5,26-31 ``` ### With radio items Use the `RadioGroup` and `RadioItem` parts to add an item that can be checked amongst others. ```vue line=8-9,22-41 ``` ### With complex items You can add extra decorative elements in the `Item` parts, such as images. ```vue line=17,21 ``` ### Constrain the content/sub-content size You may want to constrain the width of the content (or sub-content) so that it matches the trigger (or sub-trigger) width. You may also want to constrain its height to not exceed the viewport. We expose several CSS custom properties such as `--reka-dropdown-menu-trigger-width` and `--reka-dropdown-menu-content-available-height` to support this. Use them to constrain the content dimensions. ```vue line=9-12 ``` ```css line=3-4 /* styles.css */ .DropdownMenuContent { width: var(--reka-dropdown-menu-trigger-width); max-height: var(--reka-dropdown-menu-content-available-height); } ``` ### Origin-aware animations We expose a CSS custom property `--reka-dropdown-menu-content-transform-origin`. Use it to animate the content from its computed origin based on `side`, `sideOffset`, `align`, `alignOffset` and any collisions. ```vue line=9 ``` ```css line=3 /* styles.css */ .DropdownMenuContent { transform-origin: var(--reka-dropdown-menu-content-transform-origin); animation: scaleIn 0.5s ease-out; } @keyframes scaleIn { from { opacity: 0; transform: scale(0); } to { opacity: 1; transform: scale(1); } } ``` ### Collision-aware animations We expose `data-side` and `data-align` attributes. Their values will change at runtime to reflect collisions. Use them to create collision and direction-aware animations. ```vue line=9 ``` ```css line=6-11 /* styles.css */ .DropdownMenuContent { animation-duration: 0.6s; animation-timing-function: cubic-bezier(0.16, 1, 0.3, 1); } .DropdownMenuContent[data-side="top"] { animation-name: slideUp; } .DropdownMenuContent[data-side="bottom"] { animation-name: slideDown; } @keyframes slideUp { from { opacity: 0; transform: translateY(10px); } to { opacity: 1; transform: translateY(0); } } @keyframes slideDown { from { opacity: 0; transform: translateY(-10px); } to { opacity: 1; transform: translateY(0); } } ``` ## Accessibility Adheres to the [Menu Button WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button) and uses [roving tabindex](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_roving_tabindex) to manage focus movement among menu items. ### Keyboard Interactions ## Custom APIs Create your own API by abstracting the primitive parts into your own component. ### Abstract the arrow and item indicators This example abstracts the `DropdownMenuArrow` and `DropdownMenuItemIndicator` parts. It also wraps implementation details for `CheckboxItem` and `RadioItem`. #### Usage ```vue ``` #### Implementation ```ts export { default as DropdownMenuCheckboxItem } from 'DropdownMenuCheckboxItem.vue' // your-dropdown-menu.ts export { default as DropdownMenuContent } from 'DropdownMenuContent.vue' export { default as DropdownMenuRadioItem } from 'DropdownMenuRadioItem.vue' export { DropdownMenuRoot as DropdownMenu, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuRadioGroup, DropdownMenuSeparator, DropdownMenuTrigger } from 'reka-ui' ``` ```vue ``` ```vue ``` ```vue ``` --- --- url: /docs/components/editable.md description: >- Displays an input field used for editing a single line of text, rendering as static text on load. --- # Editable ## Features ## Installation Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Root Contains all the parts of an editable component. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `activationMode` | The activation event of the editable field | `"dblclick" \| "focus" \| "none"` | No | `"focus"` | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `autoResize` | Whether the editable field should auto resize | `boolean` | No | `false` | | `defaultValue` | The default value of the editable field | `string` | No | - | | `dir` | The reading direction of the calendar when applicable. If omitted, inherits globally from ConfigProvider or assumes LTR (left-to-right) reading mode. | `"ltr" \| "rtl"` | No | - | | `disabled` | Whether the editable field is disabled | `boolean` | No | `false` | | `id` | The id of the field | `string` | No | - | | `maxLength` | The maximum number of characters allowed | `number` | No | - | | `modelValue` | The value of the editable field | `string \| null` | No | - | | `name` | The name of the field. Submitted with its owning form as part of a name/value pair. | `string` | No | - | | `placeholder` | The placeholder for the editable field | `string \| { edit: string; preview: string; }` | No | `"Enter text..."` | | `readonly` | Whether the editable field is read-only | `boolean` | No | - | | `required` | When true, indicates that the user must set the value before the owning form can be submitted. | `boolean` | No | `false` | | `selectOnFocus` | Whether to select the text in the input when it is focused. | `boolean` | No | `false` | | `startWithEditMode` | Whether to start with the edit mode active | `boolean` | No | - | | `submitMode` | The submit event of the editable field | `"blur" \| "none" \| "enter" \| "both"` | No | `"blur"` | **Events** | Name | Description | Type | | --- | --- | --- | | `submit` | Event handler called when a value is submitted | `[value: string \| null]` | | `update:modelValue` | Event handler called whenever the model value changes | `[value: string]` | | `update:state` | Event handler called when the editable field changes state | `[state: "cancel" \| "submit" \| "edit"]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `isEditing` | Whether the editable field is in edit mode | `boolean` | | `modelValue` | The value of the editable field | `string \| null \| undefined` | | `isEmpty` | Whether the editable field is empty | `boolean` | | `submit` | Function to submit the value of the editable | `(): void` | | `cancel` | Function to cancel the value of the editable | `(): void` | | `edit` | Function to set the editable in edit mode | `(): void` | **Methods** | Name | Description | Type | | --- | --- | --- | | `submit` | Function to submit the value of the editable | `() => void` | | `cancel` | Function to cancel the value of the editable | `() => void` | | `edit` | Function to set the editable in edit mode | `() => void` | ### Area Contains the text parts of an editable component. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Input Contains the input of an editable component. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"input"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Preview Contains the preview of the editable component. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"span"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Edit Trigger Contains the edit trigger of the editable component. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Submit Trigger Contains the submit trigger of the editable component. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Cancel Trigger Contains the cancel trigger of the editable component. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ## Examples ### Change only on submit By default the component will submit when `blur` event triggers. We can modify the `submit-mode` prop to alter this behavior. In this case, we want to submit only when user click on `EditableSubmitTrigger`, so we change the submit mode to `none`. ```vue line=2,8 ``` ## Accessibility ### Keyboard Interactions --- --- url: /docs/utilities/focus-scope.md description: >- Manages focus within a component boundary with support for trapping and looping focus navigation. --- # Focus Scope Focus Scope provides enhanced control over keyboard focus management within component boundaries. It can trap focus within its container and optionally loop focus navigation, making it ideal for modal interfaces and other interactive components that need to manage focus states. ## API Reference **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `loop` | When true, tabbing from last item will focus first tabbable and shift+tab from first item will focus last tababble. | `boolean` | No | `false` | | `present` | Whether the scope is currently visible. Lets a consumer keep the scope mounted but hidden (e.g. display: none) and still get correct auto-focus: the mount auto-focus is skipped while not present, and re-runs when it becomes present again. Defaults to true so consumers that mount the scope only while visible are unaffected. | `boolean` | No | `true` | | `trapped` | When true, focus cannot escape the focus scope via keyboard, pointer, or a programmatic focus. | `boolean` | No | `false` | **Events** | Name | Description | Type | | --- | --- | --- | | `mountAutoFocus` | Event handler called when auto-focusing on mount. Can be prevented. | `[event: Event]` | | `unmountAutoFocus` | Event handler called when auto-focusing on unmount. Can be prevented. | `[event: Event]` | ## Example Basic usage with focus trapping ```vue line=2 ``` ### With Focus Looping Enable both trapping and looping for complete focus management: ```vue line=2 ``` ### Handling Focus Event ```vue line=2-5 ``` When using trapped mode, ensure there is always at least one focusable element within the scope to prevent focus from being trapped in an inaccessible state. --- --- url: /docs/overview/getting-started.md description: A quick tutorial to get you up and running with Reka UI. --- # Getting started ## Implementing a Popover In this quick tutorial, we will install and style the [Popover](../components/popover) component. ### 1. Install the library Install the component from your command line. ### 2. Import the parts Import and structure the parts. ```vue twoslash ``` ### 3. Add your styles Add styles where desired. ```vue ``` ### Demo Here's a complete demo. ## Summary The steps above outline briefly what's involved in using a Reka UI in your application. These components are low-level enough to give you control over how you want to wrap them. You're free to introduce your own high-level API to better suit the needs of your team and product. In a few simple steps, we've implemented a fully accessible Popover component, without having to worry about many of its complexities. * Adheres to [WAI-ARIA](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) design pattern. * Can be controlled or uncontrolled. * Customize side, alignment, offsets, collision handling. * Optionally render a pointing arrow. * Focus is fully managed and customizable. * Dismissing and layering behavior is highly customizable. ## Working with LLMs Reka UI documentation is optimized for Large Language Models (LLMs) to help you get AI-powered assistance while working with our components. ### LLM-Friendly Documentation Our documentation includes a special LLM-friendly format that makes it easier for AI assistants to understand and provide accurate help with Reka UI components. This format: * Removes visual elements and complex formatting that can confuse LLMs * Structures content in a way that's optimized for text processing * Includes comprehensive component information in a linear format * Maintains all the essential technical details while being machine-readable ### Accessing LLM Documentation You can access the LLM-optimized version of our documentation at [llms.txt](/llms.txt). This file contains: * Complete overview of all Reka UI components * Detailed API documentation * Usage examples and implementation patterns * Accessibility guidelines * Styling and customization options ### Using LLMs with Reka UI When working with LLMs like ChatGPT, Claude, or other AI assistants, you can: 1. **Reference the llms.txt file**: Direct your AI assistant to the `/llms.txt` file for comprehensive context about Reka UI 2. **Ask specific questions**: Get help with implementation, styling, or accessibility features 3. **Generate code examples**: Request custom implementations based on your specific needs 4. **Troubleshoot issues**: Get assistance with common problems or edge cases ### Example Prompts Here are some example prompts you can use with LLMs: ``` "Using the Reka UI documentation at https://reka-ui.com/llms.txt, help me implement a custom Dialog component with form validation." "Based on the Reka UI llms.txt documentation, show me how to create an accessible Select component with custom styling." "Refer to the Reka UI llms.txt file and explain how to properly implement keyboard navigation for a Combobox component." ``` By leveraging our LLM-optimized documentation, you can get more accurate and helpful responses from AI assistants when working with Reka UI components. --- --- url: /docs/components/hover-card.md description: For sighted users to preview content available behind a link. --- # HoverCard ## Features ## Installation Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Root Contains all the parts of a hover card. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `closeDelay` | The duration from when the mouse leaves the trigger or content until the hover card closes. | `number` | No | `300` | | `defaultOpen` | The open state of the hover card when it is initially rendered. Use when you do not need to control its open state. | `boolean` | No | `false` | | `enableTouch` | When true, tapping the trigger on touch devices toggles the hover card open/closed. By default touch interactions are ignored to match pointer hover semantics. | `boolean` | No | `false` | | `open` | The controlled open state of the hover card. Can be binded as v-model:open. | `boolean` | No | - | | `openDelay` | The duration from when the mouse enters the trigger until the hover card opens. | `number` | No | `700` | **Events** | Name | Description | Type | | --- | --- | --- | | `update:open` | Event handler called when the open state of the hover card changes. | `[value: boolean]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `open` | Current open state | `boolean` | ### Trigger The link that opens the hover card when hovered. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"a"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `reference` | The reference (or anchor) element that is being referred to for positioning. If not provided will use the current component as anchor. | `ReferenceElement` | No | - | ### Portal When used, portals the content part into the `body`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `defer` | Defer the resolving of a Teleport target until other parts of the application have mounted (requires Vue 3.5.0+) reference | `boolean` | No | - | | `disabled` | Disable teleport and render the component inline reference | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | | `to` | Vue native teleport component prop :to reference | `string \| HTMLElement` | No | - | ### Content The component that pops out when the hover card is open. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `align` | The preferred alignment against the trigger. May change when collisions occur. | `"start" \| "center" \| "end"` | No | - | | `alignFlip` | Flip alignment when colliding with boundary. May only occur when prioritizePosition is true. | `boolean` | No | - | | `alignOffset` | An offset in pixels from the start or end alignment options. | `number` | No | - | | `arrowPadding` | The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners. | `number` | No | - | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `avoidCollisions` | When true, overrides the side and align preferences to prevent collisions with boundary edges. | `boolean` | No | - | | `collisionBoundary` | The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. | `Element \| (Element \| null)[] \| null` | No | - | | `collisionPadding` | The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }. | `number \| Partial>` | No | - | | `dir` | The reading direction of the popper content when applicable. If omitted, inherits globally from ConfigProvider or assumes LTR (left-to-right) reading mode. | `"ltr" \| "rtl"` | No | - | | `disableUpdateOnLayoutShift` | Whether to disable the update position for the content when the layout shifted. | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | | `hideShiftedArrow` | When true, hides the arrow when it cannot be centered to the reference element. | `boolean` | No | - | | `hideWhenDetached` | Whether to hide the content when the trigger becomes fully occluded. | `boolean` | No | - | | `memoDependencies` | Reactive dependencies that should invalidate the memoized content subtree. | `unknown[]` | No | - | | `positionStrategy` | The type of CSS position property to use. | `"fixed" \| "absolute"` | No | - | | `prioritizePosition` | Force content to be position within the viewport. Might overlap the reference element, which may not be desired. | `boolean` | No | - | | `reference` | The custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element. | `ReferenceElement` | No | - | | `side` | The preferred side of the trigger to render against when open. Will be reversed when collisions occur and avoidCollisions is enabled. | `"top" \| "right" \| "bottom" \| "left"` | No | - | | `sideFlip` | Flip to the opposite side when colliding with boundary. | `boolean` | No | - | | `sideOffset` | The distance in pixels from the trigger. | `number` | No | - | | `sticky` | 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. | `"partial" \| "always"` | No | - | | `updatePositionStrategy` | Strategy to update the position of the floating element on every animation frame. | `"always" \| "optimized"` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `escapeKeyDown` | Event handler called when the escape key is down. Can be prevented. | `[event: KeyboardEvent]` | | `focusOutside` | Event handler called when the focus moves outside of the DismissableLayer. Can be prevented. | `[event: FocusOutsideEvent]` | | `interactOutside` | Event handler called when an interaction happens outside the DismissableLayer. Specifically, when a pointerdown event happens outside or focus moves outside of it. Can be prevented. | `[event: PointerDownOutsideEvent \| FocusOutsideEvent]` | | `pointerDownOutside` | Event handler called when a pointerdown event happens outside of the DismissableLayer. Can be prevented. | `[event: PointerDownOutsideEvent]` | ### Arrow An optional arrow element to render alongside the hover card. This can be used to help visually link the trigger with the `HoverCardContent`. Must be rendered inside `HoverCardContent`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"svg"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `height` | The height of the arrow in pixels. | `number` | No | `5` | | `rounded` | When true, render the rounded version of arrow. Do not work with as/asChild | `boolean` | No | - | | `width` | The width of the arrow in pixels. | `number` | No | `10` | ## Examples ### Show instantly Use the `openDelay` prop to control the time it takes for the hover card to open. ```vue line=12 ``` ### Constrain the content size You may want to constrain the width of the content so that it matches the trigger width. You may also want to constrain its height to not exceed the viewport. We expose several CSS custom properties such as `--reka-hover-card-trigger-width` and `--reka-hover-card-content-available-height` to support this. Use them to constrain the content dimensions. ```vue line=11 // index.vue ``` ```css line=3-4 /* styles.css */ .HoverCardContent { width: var(--reka-hover-card-trigger-width); max-height: var(--reka-hover-card-content-available-height); } ``` ### Origin-aware animations We expose a CSS custom property `--reka-hover-card-content-transform-origin`. Use it to animate the content from its computed origin based on `side`, `sideOffset`, `align`, `alignOffset` and any collisions. ```vue line=8 ``` ```css line=3 /* styles.css */ .HoverCardContent { transform-origin: var(--reka-hover-card-content-transform-origin); animation: scaleIn 0.5s ease-out; } @keyframes scaleIn { from { opacity: 0; transform: scale(0); } to { opacity: 1; transform: scale(1); } } ``` ### Collision-aware animations We expose `data-side` and `data-align` attributes. Their values will change at runtime to reflect collisions. Use them to create collision and direction-aware animations. ```vue line=8 ``` ```css line=6-11 /* styles.css */ .HoverCardContent { animation-duration: 0.6s; animation-timing-function: cubic-bezier(0.16, 1, 0.3, 1); } .HoverCardContent[data-side="top"] { animation-name: slideUp; } .HoverCardContent[data-side="bottom"] { animation-name: slideDown; } @keyframes slideUp { from { opacity: 0; transform: translateY(10px); } to { opacity: 1; transform: translateY(0); } } @keyframes slideDown { from { opacity: 0; transform: translateY(-10px); } to { opacity: 1; transform: translateY(0); } } ``` ## Accessibility The hover card is intended for sighted users only, the content will be inaccessible to keyboard users. ### Keyboard Interactions --- --- url: /docs/guides/inject-context.md description: >- Utilize `injectContext` to enhance component composition in Reka UI, enabling powerful and flexible UI development. --- # Inject Context Utilize `injectContext` to enhance component composition in Reka UI, enabling powerful and flexible UI development. Reka UI exposes internal `injectContext` to further extend the ability to compose and construct complex components. However, this API was primarily designed to be internal use. Thus the API might change without notice. ## Introduction to `injectContext` In Reka UI, all root component, and some other component exports an `injectContext` function, which is a key feature for managing component state and enabling seamless composition. This guide will show you how to craft your own child component based on the provided context. ## What is `injectContext`? `injectContext` is a function provided by each Reka UI component that allows you to access the internal state and methods of that component. It leverages Vue's [Provide / Inject](https://vuejs.org/guide/components/provide-inject) to provide a powerful way of extending and customizing component behavior. ## Basic Usage Here's a simple example of how to use `injectContext` with a Reka UI Accordion component: ```vue ``` ## Common Use Cases 1. **Custom Styling**: Access internal state to apply dynamic styles based on component state. 2. **Extended Functionality**: Build upon existing component logic to add new features. 3. **Complex Layouts**: Create intricate UI patterns by composing multiple components and sharing state between them. 4. **Accessibility Enhancements**: Utilize internal methods and state to improve keyboard navigation or screen reader support. ## Best Practices 1. Use `injectContext` in child components or composables, not in the component itself. 2. Always check if the injected context exists before using it, as it may be `undefined` if used outside the component's scope. 3. Prefer using provided props and events when possible, and use `injectContext` for more advanced scenarios. 4. When using TypeScript, leverage the type information provided by `injectContext` for better code quality. --- --- url: /docs/overview/installation.md --- # Installation A quick tutorial to walk through installing the packages, as well as the supported plugins. ## Installing the package ## Nuxt modules Reka UI offers Nuxt modules support. In `nuxt.config.ts`, simply add `reka-ui/nuxt` into the modules, and it will auto-imports all the components for you. ```ts export default defineNuxtConfig({ modules: ['reka-ui/nuxt'], }) ``` ## unplugin-vue-components Reka UI also has resolver for the popular [unplugin-vue-components](https://github.com/antfu/unplugin-vue-components). In `vite.config.ts`, import `reka-ui/resolver`, and configure as such and it will auto-imports all the components from Reka UI. ```ts{2,10 } import Components from 'unplugin-vue-components/vite' import RekaResolver from 'reka-ui/resolver' export default defineConfig({ plugins: [ vue(), Components({ dts: true, resolvers: [ RekaResolver() // RekaResolver({ // prefix: '' // use the prefix option to add Prefix to the imported components // }) ], }), ], }) ``` --- --- url: /docs/guides/i18n.md description: >- Reka UI support both LTR/RTL directions. Learn more about how to integrate internationalization. --- # Internationalization & RTL ## Multi-Direction Support ### Introduction This documentation provides guidance on how to utilize multi-directional support in Reka UI with SSR support. Reka UI rely on [`Floating UI`](https://floating-ui.com/) to position floating elements, which requires to be fed the current direction of the web app. Reka components are LTR by default, but you are in control of what direction (only LTR, RTL, or both) you want to support. This section provides best practices to easily support RTL direction. ### RTL [`ConfigProvider`](/docs/utilities/config-provider) is a wrapper component to provide global configurations, including the directionality of the web app. When creating localized apps that require right-to-left (RTL) reading direction, you need to wrap your application with the `ConfigProvider` component to ensure all of the primitives adjust their behavior based on the `dir` prop. To make all Reka UI RTL, wrap your entire App in `ConfigProvider` and pass the `dir` prop with the value `rtl`. Add the following code to your `app.vue` or main layout component: ```vue ``` All Reka components that are wrapped in the provider inherit the `dir` attribute. ### Dynamic Direction To dynamically change the direction of Reka UI, we could leverage the [`useTextDirection`](https://vueuse.org/core/useTextDirection/) composable and combine it with our `ConfigProvider`. But first, we need to install the [`@vueuse/core`](https://vueuse.org/) package. Then in your root Vue file: ```vue ``` To support SSR - when the server has no access to the `html` and its direction, set `initialValue` in `useTextDirection`. ```vue{5} ``` The `dir` prop doesn't support `auto` as a value, so we need an intermediate Ref to explicitly define the direction. `textDirection` is a [`Ref`](https://vuejs.org/api/reactivity-core.html#ref), and by changing the value of it to either "ltr" or "rtl", the `dir` attribute on the `html` tag changes as well. ## Internationalization Some languages are written from LTR and others are written in RTL. In a multi-language web app, you need to configure directionality alongside the translations. This is a simplified guide on how to achieve that using `reka-ui` primitives. But first, let's install some required packages. ### Dependencies We rely on [`VueI18n`](https://vue-i18n.intlify.dev/) to manage different translations we want to support. Go ahead and add some translations for the word "hello" in different languages at `main.ts`. ```ts{4-26,29} import { createApp } from 'vue' import './style.css' import App from './App.vue' import { createI18n } from 'vue-i18n' const messages = { en: { hello: 'Hello', }, fa: { hello: 'درود', }, ar: { hello: 'مرحبا', }, ja: { hello: 'こんにちは', } } const i18n = createI18n({ legacy: false, // you must set `false` to use the Composition API locale: 'en', // set default locale availableLocales: ['en', 'fa', 'ar', 'ja'], messages, }) createApp(App) .use(i18n) .mount('#app') ``` ### Language Selector After setting the translations and adding the `vue-i18n` plugin, we need a language selector in your `app.vue`. By changing the language using this `reka-ui` select primitive: 1. The translations are reactive to the new language 2. The direction of the web app is reactive to the new language ```vue ``` --- --- url: /docs/overview/introduction.md description: >- An open-source UI component library for building high-quality, accessible design systems and web apps using Vue. --- # Introduction An open-source UI component library for building high-quality, accessible design systems and web apps using Vue.js. ## ✨ Rebrand: Reka UI ✨ Presenting **Reka UI**, the new identity of [Radix Vue](https://www.radix-vue.com/) in its v2 evolution. **Reka** (pronounced `/ree·kuh/`) means "design" in [Malay](https://translate.google.com/?hl=en\&sl=ms\&tl=en\&text=reka\&op=translate), and also evokes "Eureka." Reka UI strives to deliver a low-level UI component library centered on accessibility, customization, and developer experience. Use these components as the foundation of your design system or integrate them progressively. Check out the release note [here](/docs/overview/releases#_2-0-changes) Curious about the rebrand? See the announcement in [this discussion](https://github.com/unovue/reka-ui/issues/908). ## Our Principles ### Accessibility-First Accessibility is at the heart of Reka UI. Our components align with [WAI-ARIA design patterns](https://www.w3.org/TR/wai-aria-practices-1.2) to ensure that all users, regardless of abilities, can interact with your UI effectively. We handle intricate accessibility details like aria attributes, keyboard navigation, and focus management to simplify the developer's work. ### Customizable & Unstyled Reka UI components come unstyled, providing developers the freedom to style them however they choose, using any CSS solution (vanilla CSS, preprocessors, or CSS-in-JS libraries). Our open component architecture allows you to wrap, extend, or modify each component as needed. Explore more in our [styling guide](../guides/styling). ### Open & Modular Our components are designed to be open and adaptable, allowing you to customize each element to fit your needs. Whether adding event listeners, props, or refs, Reka UI provides granular access to each component's inner workings. ### Flexible State Management Reka UI components are, by default, uncontrolled but can also be fully controlled when needed. This approach allows developers to decide on the level of state management required, offering a balance between flexibility and ease of use. ### Developer-Centric Experience We prioritize developer experience by maintaining a consistent and predictable API. Reka UI is fully-typed and structured with simplicity in mind, ensuring that components are easy to use and integrate. Our `asChild` prop allows full control over rendered elements, enhancing flexibility. ### Performance & Tree-Shaking Our library is designed with performance in mind. All components are compiled into a single package, making installation straightforward and ensuring that any unused components won’t add to your bundle size thanks to tree-shaking. Reka UI is inspired by the principles and goals of [Radix UI](https://www.radix-ui.com/), sharing a commitment to accessibility, customization, and developer-friendly design. *** # Built by Vue lovers 💚 # Credits All credits go to these open-source works and resources * Radix UI - https://radix-ui.com * React Aria - https://react-spectrum.adobe.com/react-aria * Floating UI - https://floating-ui.com * VueUse - https://vueuse.org * HeadlessUI - https://headlessui.com * Ariakit - https://ariakit.org/ --- --- url: /docs/components/label.md description: Renders an accessible label associated with controls. --- # Label ## Features ## Installation Install the component from your command line. ## Anatomy Import the component. ```vue ``` ## API Reference ### Root Contains the content for the label. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"label"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `for` | The id of the element the label is associated with. | `string` | No | - | ## Accessibility This component is based on the native `label` element, it will automatically apply the correct labelling when wrapping controls or using the `for` attribute. For your own custom controls to work correctly, ensure they use native elements such as `button` or `input` as a base. --- --- url: /docs/components/listbox.md description: A control that allows the user to toggle between checked and not checked. --- # Listbox ## Features ## Installation Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Root Contains all the parts of a listbox. An `input` will also render when used within a `form` to ensure events propagate correctly. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `by` | Use this to compare objects by a particular field, or pass your own comparison function for complete control over how objects are compared. | `string \| ((a: AcceptableValue, b: AcceptableValue) => boolean)` | No | - | | `defaultValue` | The value of the listbox when initially rendered. Use when you do not need to control the state of the Listbox | `AcceptableValue \| AcceptableValue[]` | No | - | | `dir` | The reading direction of the listbox when applicable. If omitted, inherits globally from ConfigProvider or assumes LTR (left-to-right) reading mode. | `"ltr" \| "rtl"` | No | - | | `disabled` | When true, prevents the user from interacting with listbox | `boolean` | No | - | | `highlightOnHover` | When true, hover over item will trigger highlight | `boolean` | No | - | | `modelValue` | The controlled value of the listbox. Can be binded with v-model. | `AcceptableValue \| AcceptableValue[]` | No | - | | `multiple` | Whether multiple options can be selected or not. | `boolean` | No | - | | `name` | The name of the field. Submitted with its owning form as part of a name/value pair. | `string` | No | - | | `orientation` | The orientation of the listbox. Mainly so arrow navigation is done accordingly (left & right vs. up & down) | `"vertical" \| "horizontal"` | No | `"vertical"` | | `required` | When true, indicates that the user must set the value before the owning form can be submitted. | `boolean` | No | - | | `selectionBehavior` | How multiple selection should behave in the collection. | `"replace" \| "toggle"` | No | `"toggle"` | **Events** | Name | Description | Type | | --- | --- | --- | | `entryFocus` | Event handler called when container is being focused. Can be prevented. | `[event: CustomEvent]` | | `highlight` | Event handler when highlighted element changes. | `[payload: { ref: HTMLElement; value: AcceptableValue; }]` | | `leave` | Event handler called when the mouse leave the container | `[event: Event]` | | `update:modelValue` | Event handler called when the value changes. | `[value: AcceptableValue]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `modelValue` | Current active value | `T \| T[] \| undefined` | ### Filter Input element to perform filtering. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"input"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `autoFocus` | Focus on element when mounted. | `boolean` | No | - | | `disabled` | When true, prevents the user from interacting with item | `boolean` | No | - | | `modelValue` | The controlled value of the filter. Can be binded with v-model. | `string` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `update:modelValue` | Event handler called when the value changes. | `[string]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `modelValue` | Current input values | `string \| undefined` | ### Content Contains all the listbox group and items. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Item The item component. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | When true, prevents the user from interacting with the item. | `boolean` | No | - | | `value` | The value given as data when submitted with a name. | `T` | Yes | - | **Events** | Name | Description | Type | | --- | --- | --- | | `select` | Event handler called when the selecting item. It can be prevented by calling event.preventDefault. | `[event: SelectEvent]` | ### ItemIndicator Renders when the item is selected. You can style this element directly, or you can use it as a wrapper to put an icon into, or both. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"span"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Group Used to group multiple items. use in conjunction with `ListboxGroupLabel` to ensure good accessibility via automatic labelling. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### GroupLabel Used to render the label of a group. It won't be focusable using arrow keys. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `for` | | `string` | No | - | ### Virtualizer Virtual container to achieve list virtualization. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `estimateSize` | Estimated size (in px) of each item | `number \| ((index: number) => number)` | No | - | | `options` | List of items | `T` | Yes | - | | `overscan` | Number of items rendered outside the visible area | `number` | No | - | | `textContent` | Text content for each item to achieve type-ahead feature | `((option: T) => string)` | No | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `option` | | `T` | | `virtualizer` | | `Virtualizer` | | `virtualItem` | | `VirtualItem` | ## Examples ### Binding objects as values Unlike native HTML form controls which only allow you to provide strings as values, `reka-ui` supports binding complex objects as well. ```vue line=12,16,21 ``` ### Selecting multiple values The `Listbox` component allows you to select multiple values. You can enable this by providing an array of values instead of a single value. ```vue line=12,18 ``` ### Custom filtering ```vue line=13,15-16,21,24 ``` ### Virtual List Rendering a long list of item can slow down the app, thus using virtualization would significantly improve the performance. See the [virtualization guide](../guides/virtualization.md) for more general info on virtualization. ```vue line=18-23 ``` ## Accessibility Adheres to the [Listbox WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/). ### Keyboard Interactions --- --- url: /docs/components/menubar.md description: >- A visually persistent menu common in desktop applications that provides quick access to a consistent set of commands. --- # Menubar ## Features ## Installation Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Root Contains all the parts of a menubar **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `defaultValue` | The value of the menu that should be open when initially rendered. Use when you do not need to control the value state. | `string` | No | - | | `dir` | The reading direction of the combobox when applicable. If omitted, inherits globally from ConfigProvider or assumes LTR (left-to-right) reading mode. | `"ltr" \| "rtl"` | No | - | | `loop` | When true, keyboard navigation will loop from last item to first, and vice versa. | `boolean` | No | `false` | | `modelValue` | The controlled value of the menu to open. Can be used as v-model. | `string` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `update:modelValue` | Event handler called when the value changes. | `[value: boolean]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `modelValue` | Current input values | `string` | ### Menu A top level menu item, contains a trigger with content combination. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `value` | A unique value that associates the item with an active value when the navigation menu is controlled. This prop is managed automatically when uncontrolled. | `string` | No | - | ### Trigger The button that toggles the content. By default, the `MenubarContent` will position itself against the trigger. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | When true, prevents the user from interacting with item | `boolean` | No | - | ### Portal When used, portals the content part into the `body`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `defer` | Defer the resolving of a Teleport target until other parts of the application have mounted (requires Vue 3.5.0+) reference | `boolean` | No | - | | `disabled` | Disable teleport and render the component inline reference | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | | `to` | Vue native teleport component prop :to reference | `string \| HTMLElement` | No | - | ### Content The component that pops out when a menu is open. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `align` | The preferred alignment against the trigger. May change when collisions occur. | `"start" \| "center" \| "end"` | No | `"start"` | | `alignFlip` | Flip alignment when colliding with boundary. May only occur when prioritizePosition is true. | `boolean` | No | - | | `alignOffset` | An offset in pixels from the start or end alignment options. | `number` | No | - | | `arrowPadding` | The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners. | `number` | No | - | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `avoidCollisions` | When true, overrides the side and align preferences to prevent collisions with boundary edges. | `boolean` | No | - | | `collisionBoundary` | The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. | `Element \| (Element \| null)[] \| null` | No | - | | `collisionPadding` | The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }. | `number \| Partial>` | No | - | | `disableUpdateOnLayoutShift` | Whether to disable the update position for the content when the layout shifted. | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | | `hideShiftedArrow` | When true, hides the arrow when it cannot be centered to the reference element. | `boolean` | No | - | | `hideWhenDetached` | Whether to hide the content when the trigger becomes fully occluded. | `boolean` | No | - | | `loop` | When true, keyboard navigation will loop from last item to first, and vice versa. | `boolean` | No | - | | `memoDependencies` | Reactive dependencies that should invalidate the memoized content subtree. | `unknown[]` | No | - | | `positionStrategy` | The type of CSS position property to use. | `"fixed" \| "absolute"` | No | - | | `prioritizePosition` | Force content to be position within the viewport. Might overlap the reference element, which may not be desired. | `boolean` | No | - | | `reference` | The custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element. | `ReferenceElement` | No | - | | `side` | The preferred side of the trigger to render against when open. Will be reversed when collisions occur and avoidCollisions is enabled. | `"top" \| "right" \| "bottom" \| "left"` | No | - | | `sideFlip` | Flip to the opposite side when colliding with boundary. | `boolean` | No | - | | `sideOffset` | The distance in pixels from the trigger. | `number` | No | - | | `sticky` | 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. | `"partial" \| "always"` | No | - | | `updatePositionStrategy` | Strategy to update the position of the floating element on every animation frame. | `"always" \| "optimized"` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `closeAutoFocus` | Event handler called when auto-focusing on close. Can be prevented. | `[event: Event]` | | `escapeKeyDown` | Event handler called when the escape key is down. Can be prevented. | `[event: KeyboardEvent]` | | `focusOutside` | Event handler called when the focus moves outside of the DismissableLayer. Can be prevented. | `[event: FocusOutsideEvent]` | | `interactOutside` | Event handler called when an interaction happens outside the DismissableLayer. Specifically, when a pointerdown event happens outside or focus moves outside of it. Can be prevented. | `[event: PointerDownOutsideEvent \| FocusOutsideEvent]` | | `pointerDownOutside` | Event handler called when a pointerdown event happens outside of the DismissableLayer. Can be prevented. | `[event: PointerDownOutsideEvent]` | ### Arrow An optional arrow element to render alongside a menubar menu. This can be used to help visually link the trigger with the `MenubarContent`. Must be rendered inside `MenubarContent`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"svg"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `height` | The height of the arrow in pixels. | `number` | No | `5` | | `rounded` | When true, render the rounded version of arrow. Do not work with as/asChild | `boolean` | No | - | | `width` | The width of the arrow in pixels. | `number` | No | `10` | ### Item The component that contains the menubar items. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | When true, prevents the user from interacting with the item. | `boolean` | No | - | | `textValue` | Optional text used for typeahead purposes. By default the typeahead behavior will use the .textContent of the item. Use this when the content is complex, or you have non-textual content inside. | `string` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `select` | Event handler called when the user selects an item (via mouse or keyboard). Calling event.preventDefault in this handler will prevent the menu from closing when selecting that item. | `[event: Event]` | ### Group Used to group multiple `MenubarItem`s. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Label Used to render a label. It won't be focusable using arrow keys. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### CheckboxItem An item that can be controlled and rendered like a checkbox. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | When true, prevents the user from interacting with the item. | `boolean` | No | - | | `modelValue` | The controlled checked state of the item. Can be used as v-model. | `false \| true \| "indeterminate"` | No | - | | `textValue` | Optional text used for typeahead purposes. By default the typeahead behavior will use the .textContent of the item. Use this when the content is complex, or you have non-textual content inside. | `string` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `select` | Event handler called when the user selects an item (via mouse or keyboard). Calling event.preventDefault in this handler will prevent the menu from closing when selecting that item. | `[event: Event]` | | `update:modelValue` | Event handler called when the value changes. | `[payload: boolean]` | ### RadioGroup Used to group multiple `MenubarRadioItem`s. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `modelValue` | The value of the selected item in the group. | `AcceptableValue` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `update:modelValue` | Event handler called when the value changes. | `[payload: AcceptableValue]` | ### RadioItem An item that can be controlled and rendered like a radio. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | When true, prevents the user from interacting with the item. | `boolean` | No | - | | `textValue` | Optional text used for typeahead purposes. By default the typeahead behavior will use the .textContent of the item. Use this when the content is complex, or you have non-textual content inside. | `string` | No | - | | `value` | The unique value of the item. | `AcceptableValue` | Yes | - | **Events** | Name | Description | Type | | --- | --- | --- | | `select` | Event handler called when the user selects an item (via mouse or keyboard). Calling event.preventDefault in this handler will prevent the menu from closing when selecting that item. | `[event: Event]` | ### ItemIndicator Renders when the parent `MenubarCheckboxItem` or `MenubarRadioItem` is checked. You can style this element directly, or you can use it as a wrapper to put an icon into, or both. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | ### Separator Used to visually separate items in a menubar menu. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Sub Contains all the parts of a submenu. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `defaultOpen` | The open state of the submenu when it is initially rendered. Use when you do not need to control its open state. | `boolean` | No | - | | `open` | The controlled open state of the menu. Can be used as v-model:open. | `boolean` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `update:open` | Event handler called when the open state of the submenu changes. | `[payload: boolean]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `open` | Current open state | `boolean` | ### SubTrigger An item that opens a submenu. Must be rendered inside `MenubarSub`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | When true, prevents the user from interacting with the item. | `boolean` | No | - | | `textValue` | Optional text used for typeahead purposes. By default the typeahead behavior will use the .textContent of the item. Use this when the content is complex, or you have non-textual content inside. | `string` | No | - | ### SubContent The component that pops out when a submenu is open. Must be rendered inside `MenubarSub`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `alignFlip` | Flip alignment when colliding with boundary. May only occur when prioritizePosition is true. | `boolean` | No | - | | `alignOffset` | An offset in pixels from the start or end alignment options. | `number` | No | - | | `arrowPadding` | The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners. | `number` | No | - | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `avoidCollisions` | When true, overrides the side and align preferences to prevent collisions with boundary edges. | `boolean` | No | - | | `collisionBoundary` | The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. | `Element \| (Element \| null)[] \| null` | No | - | | `collisionPadding` | The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }. | `number \| Partial>` | No | - | | `disableUpdateOnLayoutShift` | Whether to disable the update position for the content when the layout shifted. | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | | `hideShiftedArrow` | When true, hides the arrow when it cannot be centered to the reference element. | `boolean` | No | - | | `hideWhenDetached` | Whether to hide the content when the trigger becomes fully occluded. | `boolean` | No | - | | `loop` | When true, keyboard navigation will loop from last item to first, and vice versa. | `boolean` | No | - | | `memoDependencies` | Reactive dependencies that should invalidate the memoized content subtree. | `unknown[]` | No | - | | `positionStrategy` | The type of CSS position property to use. | `"fixed" \| "absolute"` | No | - | | `prioritizePosition` | Force content to be position within the viewport. Might overlap the reference element, which may not be desired. | `boolean` | No | - | | `reference` | The custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element. | `ReferenceElement` | No | - | | `sideFlip` | Flip to the opposite side when colliding with boundary. | `boolean` | No | - | | `sideOffset` | The distance in pixels from the trigger. | `number` | No | - | | `sticky` | 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. | `"partial" \| "always"` | No | - | | `updatePositionStrategy` | Strategy to update the position of the floating element on every animation frame. | `"always" \| "optimized"` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `closeAutoFocus` | Event handler called when auto-focusing on close. Can be prevented. | `[event: Event]` | | `entryFocus` | Event handler called when container is being focused. Can be prevented. | `[event: Event]` | | `escapeKeyDown` | Event handler called when the escape key is down. Can be prevented. | `[event: KeyboardEvent]` | | `focusOutside` | Event handler called when the focus moves outside of the DismissableLayer. Can be prevented. | `[event: FocusOutsideEvent]` | | `interactOutside` | Event handler called when an interaction happens outside the DismissableLayer. Specifically, when a pointerdown event happens outside or focus moves outside of it. Can be prevented. | `[event: PointerDownOutsideEvent \| FocusOutsideEvent]` | | `openAutoFocus` | Event handler called when auto-focusing on open. Can be prevented. | `[event: Event]` | | `pointerDownOutside` | Event handler called when a pointerdown event happens outside of the DismissableLayer. Can be prevented. | `[event: PointerDownOutsideEvent]` | ## Examples ### With submenus You can create submenus by using `MenubarSub` in combination with its parts. ```vue line=9-11,25-34 ``` ### With disabled items You can add special styles to disabled items via the `data-disabled` attribute. ```vue line=13 ``` ```css line=2 /* styles.css */ .MenubarItem[data-disabled] { color: gainsboro; } ``` ### With separators Use the `Separator` part to add a separator between items. ```vue line=8,20,22 ``` ### With labels Use the `Label` part to help label a section. ```vue line=5,19 ``` ### With checkbox items Use the `CheckboxItem` part to add an item that can be checked. ```vue line=3,27-32 ``` ### With radio items Use the `RadioGroup` and `RadioItem` parts to add an item that can be checked amongst others. ```vue line=9-10,26-39 ``` ### With complex items You can add extra decorative elements in the `Item` parts, such as images. ```vue line=12,16 ``` ### Constrain the content/sub-content size You may want to constrain the width of the content (or sub-content) so that it matches the trigger (or sub-trigger) width. You may also want to constrain its height to not exceed the viewport. We expose several CSS custom properties such as `--reka-menubar-trigger-width` and `--reka-menubar-content-available-height` to support this. Use them to constrain the content dimensions. ```vue line=10-13 ``` ```css line=3-4 /* styles.css */ .MenubarContent { width: var(--reka-menubar-trigger-width); max-height: var(--reka-menubar-content-available-height); } ``` ### Origin-aware animations We expose a CSS custom property `--reka-menubar-content-transform-origin`. Use it to animate the content from its computed origin based on `side`, `sideOffset`, `align`, `alignOffset` and any collisions. ```vue line=10 ``` ```css line=3 /* styles.css */ .MenubarContent { transform-origin: var(--reka-menubar-content-transform-origin); animation: scaleIn 0.5s ease-out; } @keyframes scaleIn { from { opacity: 0; transform: scale(0); } to { opacity: 1; transform: scale(1); } } ``` ### Collision-aware animations We expose `data-side` and `data-align` attributes. Their values will change at runtime to reflect collisions. Use them to create collision and direction-aware animations. ```vue line=10 ``` ```css line=6-11 /* styles.css */ .MenubarContent { animation-duration: 0.6s; animation-timing-function: cubic-bezier(0.16, 1, 0.3, 1); } .MenubarContent[data-side="top"] { animation-name: slideUp; } .MenubarContent[data-side="bottom"] { animation-name: slideDown; } @keyframes slideUp { from { opacity: 0; transform: translateY(10px); } to { opacity: 1; transform: translateY(0); } } @keyframes slideDown { from { opacity: 0; transform: translateY(-10px); } to { opacity: 1; transform: translateY(0); } } ``` ## Accessibility Adheres to the [Menu Button WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menubutton) and uses [roving tabindex](https://www.w3.org/WAI/ARIA/apg/patterns/kbd_roving_tabindex) to manage focus movement among menu items. ### Keyboard Interactions --- --- url: /docs/guides/migration.md description: >- This guide provides step-by-step instructions for developers transitioning their projects from Radix Vue to Reka UI. --- # Migration - Radix Vue to Reka UI ## Installation First and foremost, you need to install the latest `reka-ui`. Congratulation! 🎉 Now that you've installed the above package, let's perform the migration! The first 2 steps are relatively simple. Just do a global search and replace for the following changes. ## Import Statement Changes The primary change in imports is replacing `radix-vue` with `reka-ui`. ```vue ``` ## Naming Convention Changes CSS variable and data attributes names have been updated to use the `reka` prefix instead of `radix`. ```css --radix-accordion-content-width: 300px; /* [!code --] */ --reka-accordion-content-width: 300px; /* [!code ++] */ [data-radix-collection-item] {} /* [!code --] */ [data-reka-collection-item] {} /* [!code ++] */ ``` ## Component Breaking Changes ### Combobox * [Remove `filter-function` props](https://github.com/unovue/reka-ui/commit/ee8a3f2366a5c27c2bf1cc0a1ecbb0fea559a9f7) - `Combobox` has been refactored and improved to support better custom filtering. Read more. ```vue ``` * [Replace `searchTerm` props of Root to Input's `v-model`](https://github.com/unovue/reka-ui/commit/e1bab6598c3533dfbf6a86ad26b471ab826df069#diff-833593a5ce28a8c3fabc7d77462b116405e25df2b93bcab449798b5799e73474) * [Move `displayValue` props from Root to Input](https://github.com/unovue/reka-ui/commit/e1bab6598c3533dfbf6a86ad26b471ab826df069#diff-833593a5ce28a8c3fabc7d77462b116405e25df2b93bcab449798b5799e73474) ```vue ``` ### Arrow * [Improve arrow polygon](https://github.com/unovue/reka-ui/commit/ac8f3c34760f4c9c0f952ecd027b32951b9c416c) - Change the svg polygon to allow better styling. ### Form component * [Rename controlled state to `v-model`](https://github.com/unovue/reka-ui/commit/87aa5ba6016fa7a98f02ea43062212906b2633a0) - Replace `v-model:checked`, `v-model:pressed` with more familiar API for form component. ```vue ``` * [Reposition `VisuallyHidden`](https://github.com/unovue/reka-ui/commit/107389a9c230d2c94232887b9cbe2710222564aa) - Previously, `VisuallyHidden` were positioned at the root node, causing style scoped to not be applied. ### Menu CheckboxItem * Similar to the changes in form component, the API for binding `CheckboxItem` has been changed from `v-model:checked` to `v-model`. ```vue ``` ### Pagination * [Required `itemsPerPage` prop](https://github.com/unovue/reka-ui/commit/37bba0c26a3cbe7e7e3e4ac36770be3ef5224f0c) - Instead of default `itemsPerPage` value, now it is required as to provide a more explicit hint about the page size. ```vue ``` ### Calendar * [Remove deprecated step prop](https://github.com/unovue/reka-ui/commit/ec146dd8fa0f95f64baf0b29c3424ee31cfb9666) - Use `prevPage/nextPage` props for greater control. ```vue ``` ### Select * [`SelectValue` no longer render teleported element](https://github.com/unovue/reka-ui/commit/6a623484d610cc3b7c1a23a77c253c8e95cef518) - Previous implementation of `SelectValue` will render the selected `SelectItem` via teleporting fragment. This causes SSR flickering, and it is unnecessarily computation. ```vue ``` ### Presence To have better supports for SSR content, we also modify the logic around the usage of `forceMount` for component that utilize Presence: * `Accordion` * `Collapsible` * `Tabs` * `NavigationMenu` [`forceMount` will now render the component](https://github.com/unovue/reka-ui/commit/6f7f29abe79ac6c3ace117a398b6f7613ab6d2bc) eventhough the state is inactive. You are now required to handle the visibility logic of the component manually. ```vue ``` ## For Nuxt module users If you are using Nuxt, you need to update your module import. ```ts // nuxt.config.ts export default defineNuxtConfig({ modules: [ 'radix-vue/nuxt', // [!code --] 'reka-ui/nuxt', // [!code ++] ], }) ``` --- --- url: /docs/components/month-picker.md description: Presents a calendar view tailored for selecting months. --- # Month Picker Alpha ## Features ## Preface The component depends on the [@internationalized/date](https://react-spectrum.adobe.com/internationalized/date/index.html) package, which solves a lot of the problems that come with working with dates and times in JavaScript. We highly recommend reading through the documentation for the package to get a solid feel for how it works, and you'll need to install it in your project to use the date-related components. ## Installation Install the date package. Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Root Contains all the parts of a month picker **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `calendarLabel` | The accessible label for the month picker | `string` | No | - | | `defaultPlaceholder` | The default placeholder date | `DateValue` | No | - | | `defaultValue` | The default value for the month picker | `DateValue` | No | - | | `dir` | The reading direction of the calendar when applicable. If omitted, inherits globally from ConfigProvider or assumes LTR. | `"ltr" \| "rtl"` | No | - | | `disabled` | Whether the month picker is disabled | `boolean` | No | `false` | | `initialFocus` | If true, the month picker will focus the selected month, today, or the first month of the year on mount | `boolean` | No | `false` | | `isMonthDisabled` | A function that returns whether or not a month is disabled | `Matcher` | No | - | | `isMonthUnavailable` | A function that returns whether or not a month is unavailable | `Matcher` | No | - | | `locale` | The locale to use for formatting dates | `string` | No | - | | `maxValue` | The maximum date that can be selected | `DateValue` | No | - | | `minValue` | The minimum date that can be selected | `DateValue` | No | - | | `modelValue` | The controlled selected month value of the month picker. Can be bound as v-model. | `DateValue \| DateValue[] \| null` | No | - | | `multiple` | Whether multiple months can be selected | `boolean` | No | `false` | | `nextPage` | A function that returns the next page of the month picker. Receives the current placeholder as an argument. | `((placeholder: DateValue) => DateValue)` | No | - | | `placeholder` | The placeholder date, which is used to determine what year to display when no date is selected | `DateValue` | No | - | | `preventDeselect` | Whether or not to prevent the user from deselecting a date without selecting another date first | `boolean` | No | `false` | | `prevPage` | A function that returns the previous page of the month picker. Receives the current placeholder as an argument. | `((placeholder: DateValue) => DateValue)` | No | - | | `readonly` | Whether the month picker is readonly | `boolean` | No | `false` | **Events** | Name | Description | Type | | --- | --- | --- | | `update:modelValue` | Event handler called whenever the model value changes | `[date: DateValue \| DateValue[]]` | | `update:placeholder` | Event handler called whenever the placeholder value changes | `[date: DateValue]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `date` | The current date of the placeholder | `DateValue` | | `grid` | The grid of months | `Grid` | | `locale` | The month picker locale | `string` | | `modelValue` | The current selected value | `DateValue \| DateValue[] \| undefined` | ### Header Contains the navigation buttons and the heading segments. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Prev Button Calendar navigation button. It navigates the calendar one year in the past. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `prevPage` | The function to be used for the prev page. Overwrites the prevPage function set on the MonthPickerRoot. | `((placeholder: DateValue) => DateValue)` | No | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `disabled` | Current disable state | `boolean` | ### Next Button Calendar navigation button. It navigates the calendar one year in the future. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `nextPage` | The function to be used for the next page. Overwrites the nextPage function set on the MonthPickerRoot. | `((placeholder: DateValue) => DateValue)` | No | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `disabled` | Current disable state | `boolean` | ### Heading Heading for displaying the current year. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `headingValue` | Current year heading | `string` | ### Grid Container for wrapping the month picker grid. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"table"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Grid Body Container for wrapping the grid body. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"tbody"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Grid Row Container for wrapping the grid row. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"tr"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Cell Container for wrapping the month picker cells. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"td"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `date` | The date value for the cell | `DateValue` | Yes | - | ### Cell Trigger Interactable container for displaying the cell months. Clicking it selects the month. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `month` | The date value provided to the cell trigger | `DateValue` | Yes | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `monthValue` | Current month value (short name) | `string` | | `disabled` | Current disable state | `boolean` | | `selected` | Current selected state | `boolean` | | `today` | Current month/year is today state | `boolean` | | `unavailable` | Current unavailable state | `boolean` | ## Accessibility ### Keyboard Interactions --- --- url: /docs/components/month-range-picker.md description: Presents a calendar view tailored for selecting month ranges. --- # Month Range Picker Alpha ## Features ## Preface The component depends on the [@internationalized/date](https://react-spectrum.adobe.com/internationalized/date/index.html) package, which solves a lot of the problems that come with working with dates and times in JavaScript. We highly recommend reading through the documentation for the package to get a solid feel for how it works, and you'll need to install it in your project to use the date-related components. ## Installation Install the date package. Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Root Contains all the parts of a month range picker **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `allowNonContiguousRanges` | When combined with isMonthUnavailable, determines whether non-contiguous ranges may be selected. | `boolean` | No | `false` | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `calendarLabel` | The accessible label for the calendar | `string` | No | - | | `defaultPlaceholder` | The default placeholder date | `DateValue` | No | - | | `defaultValue` | The default value for the calendar | `DateRange` | No | `{ start: undefined, end: undefined }` | | `dir` | The reading direction of the calendar when applicable. | `"ltr" \| "rtl"` | No | - | | `disabled` | Whether or not the calendar is disabled | `boolean` | No | `false` | | `fixedDate` | Which part of the range should be fixed | `"start" \| "end"` | No | - | | `initialFocus` | If true, the calendar will focus the selected month on mount | `boolean` | No | `false` | | `isMonthDisabled` | A function that returns whether or not a month is disabled | `Matcher` | No | - | | `isMonthUnavailable` | A function that returns whether or not a month is unavailable | `Matcher` | No | - | | `locale` | The locale to use for formatting dates | `string` | No | - | | `maximumMonths` | The maximum number of months that can be selected in a range | `number` | No | - | | `maxValue` | The maximum date that can be selected | `DateValue` | No | - | | `minValue` | The minimum date that can be selected | `DateValue` | No | - | | `modelValue` | The controlled selected month range of the month range picker. Can be bound as v-model. | `DateRange \| null` | No | - | | `nextPage` | A function that returns the next page of the calendar. | `((placeholder: DateValue) => DateValue)` | No | - | | `placeholder` | The placeholder date, which is used to determine what year to display when no date is selected. | `DateValue` | No | - | | `preventDeselect` | Whether or not to prevent the user from deselecting a date without selecting another date first | `boolean` | No | `false` | | `prevPage` | A function that returns the previous page of the calendar. | `((placeholder: DateValue) => DateValue)` | No | - | | `readonly` | Whether or not the calendar is readonly | `boolean` | No | `false` | **Events** | Name | Description | Type | | --- | --- | --- | | `update:modelValue` | Event handler called whenever the model value changes | `[date: DateRange]` | | `update:placeholder` | Event handler called whenever the placeholder value changes | `[date: DateValue]` | | `update:startValue` | Event handler called whenever the start value changes | `[date: DateValue]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `date` | The current date of the placeholder | `DateValue` | | `grid` | The grid of months | `Grid` | | `locale` | The calendar locale | `string` | | `modelValue` | The current date range | `DateRange` | ### Header Contains the navigation buttons and the heading segments. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Prev Button Calendar navigation button. It navigates the calendar one year in the past. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `prevPage` | The function to be used for the prev page. Overwrites the prevPage function set on the Root. | `((placeholder: DateValue) => DateValue)` | No | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `disabled` | Current disable state | `boolean` | ### Next Button Calendar navigation button. It navigates the calendar one year in the future. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `nextPage` | The function to be used for the next page. Overwrites the nextPage function set on the Root. | `((placeholder: DateValue) => DateValue)` | No | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `disabled` | Current disable state | `boolean` | ### Heading Heading for displaying the current year. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `headingValue` | Current year heading | `string` | ### Grid Container for wrapping the month range picker grid. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"table"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Grid Body Container for wrapping the grid body. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"tbody"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Grid Row Container for wrapping the grid row. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"tr"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Cell Container for wrapping the month range picker cells. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"td"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `date` | The date value for the cell | `DateValue` | Yes | - | ### Cell Trigger Interactable container for displaying the cell months. Clicking it selects the month. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `month` | The date value provided to the cell trigger | `DateValue` | Yes | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `monthValue` | Current month value (short name) | `string` | | `disabled` | Current disable state | `boolean` | | `selected` | Current selected state | `boolean` | | `today` | Current month is today's month state | `boolean` | | `unavailable` | Current unavailable state | `boolean` | | `highlighted` | Current highlighted state | `boolean` | | `highlightedStart` | Current highlighted start state | `boolean` | | `highlightedEnd` | Current highlighted end state | `boolean` | | `selectionStart` | Current selection start state | `boolean` | | `selectionEnd` | Current selection end state | `boolean` | ## Accessibility ### Keyboard Interactions --- --- url: /docs/guides/namespaced-components.md --- # Namespaced components Reka UI design pattern is to create primitives for each component, and allow user to construct or [compose](./composition) components however they want. However, importing all the necessary components 1-by-1 can be quite an effort, and the user might sometimes accidentally leave out an important component. ## How to use? First, you need to import the namespaced components via `reka-ui/namespaced` in your Vue component. ```vue line=2 ``` Then, you can use all the relevant components within the namespace. ```vue line=6-17 ``` --- --- url: /docs/components/navigation-menu.md description: A collection of links for navigating websites. --- # Navigation Menu ## Features ## Installation Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Root Contains all the parts of a navigation menu. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"nav"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `defaultValue` | The value of the menu item that should be active when initially rendered. Use when you do not need to control the value state. | `string` | No | - | | `delayDuration` | The duration from when the pointer enters the trigger until the tooltip gets opened. | `number` | No | `200` | | `dir` | The reading direction of the combobox when applicable. If omitted, inherits globally from ConfigProvider or assumes LTR (left-to-right) reading mode. | `"ltr" \| "rtl"` | No | - | | `disableClickTrigger` | If true, menu cannot be open by click on trigger | `boolean` | No | `false` | | `disableHoverTrigger` | If true, menu cannot be open by hover on trigger | `boolean` | No | `false` | | `disablePointerLeaveClose` | If true, menu will not close during pointer leave event | `boolean` | No | - | | `modelValue` | The controlled value of the menu item to activate. Can be used as v-model. | `string` | No | - | | `orientation` | The orientation of the menu. | `"vertical" \| "horizontal"` | No | `"horizontal"` | | `skipDelayDuration` | How much time a user has to enter another trigger without incurring a delay again. | `number` | No | `300` | | `unmountOnHide` | When true, the element will be unmounted on closed state. | `boolean` | No | `true` | **Events** | Name | Description | Type | | --- | --- | --- | | `update:modelValue` | Event handler called when the value changes. | `[value: string]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `modelValue` | Current input values | `string` | ### Sub Signifies a submenu. Use it in place of the root part when nested to create a submenu. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `defaultValue` | The value of the menu item that should be active when initially rendered. Use when you do not need to control the value state. | `string` | No | - | | `modelValue` | The controlled value of the sub menu item to activate. Can be used as v-model. | `string` | No | - | | `orientation` | The orientation of the menu. | `"vertical" \| "horizontal"` | No | `"horizontal"` | **Events** | Name | Description | Type | | --- | --- | --- | | `update:modelValue` | Event handler called when the value changes. | `[value: string]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `modelValue` | Current input values | `string` | ### List Contains the top level menu items. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"ul"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Item A top level menu item, contains a link or trigger with content combination. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"li"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `value` | A unique value that associates the item with an active value when the navigation menu is controlled. This prop is managed automatically when uncontrolled. | `string` | No | - | ### Trigger The button that toggles the content. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | When true, prevents the user from interacting with item | `boolean` | No | - | ### Content Contains the content associated with each trigger. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disableOutsidePointerEvents` | When true, hover/focus/click interactions will be disabled on elements outside the DismissableLayer. Users will need to click twice on outside elements to interact with them: once to close the DismissableLayer, and again to trigger the element. | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `escapeKeyDown` | Event handler called when the escape key is down. Can be prevented. | `[event: KeyboardEvent]` | | `focusOutside` | Event handler called when the focus moves outside of the DismissableLayer. Can be prevented. | `[event: FocusOutsideEvent]` | | `interactOutside` | Event handler called when an interaction happens outside the DismissableLayer. Specifically, when a pointerdown event happens outside or focus moves outside of it. Can be prevented. | `[event: PointerDownOutsideEvent \| FocusOutsideEvent]` | | `pointerDownOutside` | Event handler called when a pointerdown event happens outside of the DismissableLayer. Can be prevented. | `[event: PointerDownOutsideEvent]` | ### Link A navigational link. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `active` | Used to identify the link as the currently active page. | `boolean` | No | - | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"a"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `select` | Event handler called when the user selects a link (via mouse or keyboard). Calling event.preventDefault in this handler will prevent the navigation menu from closing when selecting that link. | `[payload: CustomEvent<{ originalEvent: Event; }>]` | ### Indicator An optional indicator element that renders below the list, is used to highlight the currently active trigger. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | ### Viewport An optional viewport element that is used to render active content outside of the list. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `align` | Placement of the viewport for css variables (--reka-navigation-menu-viewport-left, --reka-navigation-menu-viewport-top). | `"start" \| "center" \| "end"` | No | `"center"` | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | ## Examples ### Vertical You can create a vertical menu by using the `orientation` prop. ```vue line=16 ``` ### Flexible layouts Use the `Viewport` part when you need extra control over where `Content` is rendered. This can be helpful when your design requires an adjusted DOM structure or if you need flexibility to achieve [advanced animation](/docs/components/navigation-menu#advanced-animation). Tab focus will be maintained automatically. ```vue line=26 ``` ### With indicator You can use the optional `Indicator` part to highlight the currently active `Trigger`, this is useful when you want to provide an animated visual cue such as an arrow or highlight to accompany the `Viewport`. ```vue line=24 ``` ```css /* styles.css */ .NavigationMenuIndicator { background-color: grey; position: absolute; transition: width, transform, 250ms ease; } .NavigationMenuIndicator[data-orientation="horizontal"] { left: 0; height: 3px; transform: translateX(var(--reka-navigation-menu-indicator-position)); width: var(--reka-navigation-menu-indicator-size); } ``` ### With submenus Create a submenu by nesting your `NavigationMenu` and using the `Sub` part in place of its `Root`. Submenus work differently to `Root` navigation menus and are similar to [`Tabs`](/docs/components/tabs) in that one item should always be active, so be sure to assign and set a `defaultValue`. ```vue line=7,23-34 ``` ### With client side routing If you need to use the `RouterLink` component provided by your routing package then we recommend adding `asChild="true"` to `NavigationMenuLink`, or setting `as="RouterLink"`. This will ensure accessibility and consistent keyboard control is maintained: ```vue line=12-14,19-21 ``` ### Advanced animation We expose `--reka-navigation-menu-viewport-[width|height]` and `data-motion['from-start'|'to-start'|'from-end'|'to-end']` attributes to allow you to animate `Viewport` size and `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. ```vue line=17,23,29 ``` ```css line=9-20,24,25 /* styles.css */ .NavigationMenuContent { position: absolute; top: 0; left: 0; animation-duration: 250ms; animation-timing-function: ease; } .NavigationMenuContent[data-motion="from-start"] { animation-name: enterFromLeft; } .NavigationMenuContent[data-motion="from-end"] { animation-name: enterFromRight; } .NavigationMenuContent[data-motion="to-start"] { animation-name: exitToLeft; } .NavigationMenuContent[data-motion="to-end"] { animation-name: exitToRight; } .NavigationMenuViewport { position: relative; width: var(--reka-navigation-menu-viewport-width); height: var(--reka-navigation-menu-viewport-height); transition: width, height, 250ms ease; } @keyframes enterFromRight { from { opacity: 0; transform: translateX(200px); } to { opacity: 1; transform: translateX(0); } } @keyframes enterFromLeft { from { opacity: 0; transform: translateX(-200px); } to { opacity: 1; transform: translateX(0); } } @keyframes exitToRight { from { opacity: 1; transform: translateX(0); } to { opacity: 0; transform: translateX(200px); } } @keyframes exitToLeft { from { opacity: 1; transform: translateX(0); } to { opacity: 0; transform: translateX(-200px); } } ``` ## Accessibility Adheres to the [`navigation` role requirements](https://www.w3.org/TR/wai-aria-1.2/#navigation). ### Differences to menubar `NavigationMenu` should not be confused with `menubar`, although this primitive shares the name `menu` in the colloquial sense to refer to a set of navigation links, it does not use the WAI-ARIA `menu` role. This is because `menu` and `menubars` behave like native operating system menus most commonly found in desktop application windows, as such they feature complex functionality like composite focus management and first-character navigation. These features are often considered [unnecessary for website navigation](https://github.com/w3c/aria-practices/issues/353) and at worst can confuse users who are familiar with established website patterns. See the W3C [Disclosure Navigation Menu](https://w3c.github.io/aria-practices/examples/disclosure/disclosure-navigation.html) example for more information. ### Link usage and aria-current It's important to use `NavigationMenuLink` for all navigational links within a menu, this not only applies to the main list but also within any content rendered via `NavigationMenuContent`. This will ensure consistent keyboard interactions and accessibility while also giving access to the `active` prop for setting `aria-current` and the active styles. See [this example](/docs/components/navigation-menu#with-client-side-routing) for more information on usage with third party routing components. ### Keyboard Interactions --- --- url: /docs/components/number-field.md description: >- A number field allows a user to enter a number and increment or decrement the value using stepper buttons. --- # Number Field ## Features ## Installation Install the number package. Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Root Contains all the parts of a number field. An `input` will also render when used within a `form` to ensure events propagate correctly. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `defaultValue` | | `number` | No | - | | `disabled` | When true, prevents the user from interacting with the Number Field. | `boolean` | No | - | | `disableWheelChange` | When true, prevents the value from changing on wheel scroll. | `boolean` | No | - | | `focusOnChange` | When true, the input will be focused when the value changes. | `boolean` | No | `true` | | `formatOptions` | Formatting options for the value displayed in the number field. This also affects what characters are allowed to be typed by the user. | `Intl.NumberFormatOptions` | No | - | | `id` | Id of the element | `string` | No | - | | `invertWheelChange` | When true, inverts the direction of the wheel change. | `boolean` | No | - | | `locale` | The locale to use for formatting and currencies | `string` | No | - | | `max` | The largest value allowed for the input. | `number` | No | - | | `min` | The smallest value allowed for the input. | `number` | No | - | | `modelValue` | | `number \| null` | No | - | | `name` | The name of the field. Submitted with its owning form as part of a name/value pair. | `string` | No | - | | `readonly` | When true, the Number Field is read-only. | `boolean` | No | - | | `required` | When true, indicates that the user must set the value before the owning form can be submitted. | `boolean` | No | - | | `step` | The amount that the input value changes with each increment or decrement "tick". | `number` | No | `1` | | `stepSnapping` | When false, prevents the value from snapping to the nearest increment of the step value | `boolean` | No | `true` | **Events** | Name | Description | Type | | --- | --- | --- | | `update:modelValue` | Event handler called when the value changes. | `[val: number]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `modelValue` | | `number \| undefined` | | `textValue` | | `string` | | `readonly` | | `boolean` | ### Input Input The input component that renders the text value based on value and format options. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"input"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Increment The button that increases the value. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | | `boolean` | No | - | ### Decrement The button that decreases the value. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | | `boolean` | No | - | ## Example ### Decimal All options supported by `Intl.NumberFormat` are supported, including configuration of minimum and maximum fraction digits, sign display, grouping separators, etc. ```vue line=3-7 ``` ### Percentage You can set `formatOptions.style` to `percent` to treat the value as a percentage. You need to set the step to 0.01 manually to allow an appropriate step size in this mode. ```vue line=3-7 ``` ### Currency You can set `formatOptions.style` to `currency` to treat the value as a currency value. The currency option must also be passed to set the currency code (e.g., USD). If you need to allow the user to change the currency, you should include a separate dropdown next to the number field. The number field itself will not determine the currency from the user input. ```vue line=4-9 ``` ## Accessibility Adheres to the [Spinbutton WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton). ### Keyboard Interactions --- --- url: /docs/components/pagination.md description: Displays data in paged format and provides navigation between pages. --- # Pagination ## Features ## Installation Install the component from your command line. ### Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Root Contains all of the paginations parts. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"nav"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `defaultPage` | The value of the page that should be active when initially rendered. Use when you do not need to control the value state. | `number` | No | `1` | | `disabled` | When true, prevents the user from interacting with item | `boolean` | No | - | | `itemsPerPage` | Number of items per page | `number` | Yes | - | | `page` | The controlled value of the current page. Can be binded as v-model:page. | `number` | No | - | | `showEdges` | When true, always show first page, last page, and ellipsis | `boolean` | No | `false` | | `siblingCount` | Number of sibling should be shown around the current page | `number` | No | `2` | | `total` | Number of items in your list | `number` | No | `0` | **Events** | Name | Description | Type | | --- | --- | --- | | `update:page` | Event handler called when the page value changes | `[value: number]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `page` | Current page state | `number` | | `pageCount` | Number of pages | `number` | ### List Used to show the list of pages. It also makes pagination accessible to assistive technologies. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `items` | Pages item | `{ type: "ellipsis"; } \| { type: "page"; value: number; }` | ### Item Used to render the button that changes the current page. ### Ellipsis Placeholder element when the list is long, and only a small amount of `siblingCount` was set and `showEdges` was set to `true`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### First Triggers that set the page value to 1 **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Prev Triggers that set the page value to the previous page **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Next Triggers that set the page value to the next page **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Last Triggers that set the page value to the last page **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ## Examples ### With ellipsis You can add `PaginationEllipsis` as a visual cue for more previous and after items. ```vue line=10,14 ``` ### With first/last button You can add `PaginationFirst` to allow user to navigate to first page, or `PaginationLast` to navigate to last page. ```vue line=8,10 ``` ### Control page programmatically You can control the current page by passing it a reactive value. ```vue line=6,10,11 ``` ## Keyboard Interactions --- --- url: /docs/components/pin-input.md description: A sequence of one-character alphanumeric inputs. --- # Pin Input ## Features ## Installation Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Root Contains all the parts of a pin. An `input` will also render when used within a `form` to ensure events propagate correctly. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `defaultValue` | The default value of the pin inputs when it is initially rendered. Use when you do not need to control its checked state. | `PinInputValue` | No | - | | `dir` | The reading direction of the combobox when applicable. If omitted, inherits globally from ConfigProvider or assumes LTR (left-to-right) reading mode. | `"ltr" \| "rtl"` | No | - | | `disabled` | When true, prevents the user from interacting with the pin input | `boolean` | No | - | | `id` | Id of the element | `string` | No | - | | `mask` | When true, pin inputs will be treated as password. | `boolean` | No | - | | `modelValue` | The controlled checked state of the pin input. Can be binded as v-model. | `PinInputValue \| null` | No | - | | `name` | The name of the field. Submitted with its owning form as part of a name/value pair. | `string` | No | - | | `otp` | When true, mobile devices will autodetect the OTP from messages or clipboard, and enable the autocomplete field. | `boolean` | No | - | | `placeholder` | The placeholder character to use for empty pin-inputs. | `string` | No | `""` | | `required` | When true, indicates that the user must set the value before the owning form can be submitted. | `boolean` | No | - | | `type` | Input type for the inputs. | `Type` | No | `"text" as any` | **Events** | Name | Description | Type | | --- | --- | --- | | `complete` | | `[value: PinInputValue]` | | `update:modelValue` | Event handler called when the value changes. | `[value: PinInputValue]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `modelValue` | Current input values | \`\` | ### Input Input field for Pin Input. You can add as many input as you like. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"input"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | When true, prevents the user from interacting with the pin input | `boolean` | No | - | | `index` | Position of the value this input binds to. | `number` | Yes | - | ## Examples ### OTP mode You can set the pin input to `otp` mode by setting otp to `true`. ```vue{6} ``` ### Numeric mode You can set the pin input to only accept `number` type by setting type to `number`. ```vue{6} ``` ## Accessibility ### Keyboard Interactions --- --- url: /docs/components/popover.md description: 'Displays rich content in a portal, triggered by a button.' --- # Popover ## Features ## Installation Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Root Contains all the parts of a popover. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `defaultOpen` | The open state of the popover when it is initially rendered. Use when you do not need to control its open state. | `boolean` | No | `false` | | `modal` | The modality of the popover. When set to true, interaction with outside elements will be disabled and only popover content will be visible to screen readers. | `boolean` | No | `false` | | `open` | The controlled open state of the popover. | `boolean` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `update:open` | Event handler called when the open state of the popover changes. | `[value: boolean]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `open` | Current open state | `boolean` | | `close` | Close the popover | `(): void` | ### Trigger The button that toggles the popover. By default, the `PopoverContent` will position itself against the trigger. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Anchor An optional element to position the `PopoverContent` against. If this part is not used, the content will position alongside the PopoverTrigger. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `reference` | The reference (or anchor) element that is being referred to for positioning. If not provided will use the current component as anchor. | `ReferenceElement` | No | - | ### Portal When used, portals the content part into the `body`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `defer` | Defer the resolving of a Teleport target until other parts of the application have mounted (requires Vue 3.5.0+) reference | `boolean` | No | - | | `disabled` | Disable teleport and render the component inline reference | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | | `to` | Vue native teleport component prop :to reference | `string \| HTMLElement` | No | - | ### Content The component that pops out when the popover is open. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `align` | The preferred alignment against the trigger. May change when collisions occur. | `"start" \| "center" \| "end"` | No | - | | `alignFlip` | Flip alignment when colliding with boundary. May only occur when prioritizePosition is true. | `boolean` | No | - | | `alignOffset` | An offset in pixels from the start or end alignment options. | `number` | No | - | | `arrowPadding` | The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners. | `number` | No | - | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `avoidCollisions` | When true, overrides the side and align preferences to prevent collisions with boundary edges. | `boolean` | No | - | | `collisionBoundary` | The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. | `Element \| (Element \| null)[] \| null` | No | - | | `collisionPadding` | The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }. | `number \| Partial>` | No | - | | `dir` | The reading direction of the popper content when applicable. If omitted, inherits globally from ConfigProvider or assumes LTR (left-to-right) reading mode. | `"ltr" \| "rtl"` | No | - | | `disableOutsidePointerEvents` | When true, hover/focus/click interactions will be disabled on elements outside the DismissableLayer. Users will need to click twice on outside elements to interact with them: once to close the DismissableLayer, and again to trigger the element. | `boolean` | No | - | | `disableUpdateOnLayoutShift` | Whether to disable the update position for the content when the layout shifted. | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | | `hideShiftedArrow` | When true, hides the arrow when it cannot be centered to the reference element. | `boolean` | No | - | | `hideWhenDetached` | Whether to hide the content when the trigger becomes fully occluded. | `boolean` | No | - | | `memoDependencies` | Reactive dependencies that should invalidate the memoized content subtree. | `unknown[]` | No | - | | `positionStrategy` | The type of CSS position property to use. | `"fixed" \| "absolute"` | No | - | | `prioritizePosition` | Force content to be position within the viewport. Might overlap the reference element, which may not be desired. | `boolean` | No | - | | `reference` | The custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element. | `ReferenceElement` | No | - | | `side` | The preferred side of the trigger to render against when open. Will be reversed when collisions occur and avoidCollisions is enabled. | `"top" \| "right" \| "bottom" \| "left"` | No | - | | `sideFlip` | Flip to the opposite side when colliding with boundary. | `boolean` | No | - | | `sideOffset` | The distance in pixels from the trigger. | `number` | No | - | | `sticky` | 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. | `"partial" \| "always"` | No | - | | `updatePositionStrategy` | Strategy to update the position of the floating element on every animation frame. | `"always" \| "optimized"` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `closeAutoFocus` | Event handler called when auto-focusing on close. Can be prevented. | `[event: Event]` | | `escapeKeyDown` | Event handler called when the escape key is down. Can be prevented. | `[event: KeyboardEvent]` | | `focusOutside` | Event handler called when the focus moves outside of the DismissableLayer. Can be prevented. | `[event: FocusOutsideEvent]` | | `interactOutside` | Event handler called when an interaction happens outside the DismissableLayer. Specifically, when a pointerdown event happens outside or focus moves outside of it. Can be prevented. | `[event: PointerDownOutsideEvent \| FocusOutsideEvent]` | | `openAutoFocus` | Event handler called when auto-focusing on open. Can be prevented. | `[event: Event]` | | `pointerDownOutside` | Event handler called when a pointerdown event happens outside of the DismissableLayer. Can be prevented. | `[event: PointerDownOutsideEvent]` | ### Arrow An optional arrow element to render alongside the popover. This can be used to help visually link the anchor with the `PopoverContent`. Must be rendered inside `PopoverContent`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"svg"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `height` | The height of the arrow in pixels. | `number` | No | `5` | | `rounded` | When true, render the rounded version of arrow. Do not work with as/asChild | `boolean` | No | - | | `width` | The width of the arrow in pixels. | `number` | No | `10` | ### Close The button that closes an open popover. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ## Examples ### Constrain the content size You may want to constrain the width of the content so that it matches the trigger width. You may also want to constrain its height to not exceed the viewport. We expose several CSS custom properties such as `--reka-popover-trigger-width` and `--reka-popover-content-available-height` to support this. Use them to constrain the content dimensions. ```vue line=10,11 ``` ```css line=3,4 /* styles.css */ .PopoverContent { width: var(--reka-popover-trigger-width); max-height: var(--reka-popover-content-available-height); } ``` ### Origin-aware animations We expose a CSS custom property `--reka-popover-content-transform-origin`. Use it to animate the content from its computed origin based on `side`, `sideOffset`, `align`, `alignOffset` and any collisions. ```vue line=9 ``` ```css line=3 /* styles.css */ .PopoverContent { transform-origin: var(--reka-popover-content-transform-origin); animation: scaleIn 0.5s ease-out; } @keyframes scaleIn { from { opacity: 0; transform: scale(0); } to { opacity: 1; transform: scale(1); } } ``` ### Collision-aware animations We expose `data-side` and `data-align` attributes. Their values will change at runtime to reflect collisions. Use them to create collision and direction-aware animations. ```vue line=9 ``` ```css line=6-11 /* styles.css */ .PopoverContent { animation-duration: 0.6s; animation-timing-function: cubic-bezier(0.16, 1, 0.3, 1); } .PopoverContent[data-side="top"] { animation-name: slideUp; } .PopoverContent[data-side="bottom"] { animation-name: slideDown; } @keyframes slideDown { from { opacity: 0; transform: translateY(-10px); } to { opacity: 1; transform: translateY(0); } } @keyframes slideUp { from { opacity: 0; transform: translateY(10px); } to { opacity: 1; transform: translateY(0); } } ``` ### With custom anchor You can anchor the content to another element if you do not want to use the trigger as the anchor. ```vue line=7-11 ``` ```css /* styles.css */ .Row { background-color: gainsboro; padding: 20px; } ``` ### Close using slot props Alternatively, you can use the `close` method provided by the `PopoverRoot` slot props to programmatically close the popover. ```vue line=4,8,16-20 ``` ## Accessibility Adheres to the [Dialog WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/). ### Keyboard Interactions ## Custom APIs Create your own API by abstracting the primitive parts into your own component. #### Abstract the arrow and set default configuration This example abstracts the `PopoverArrow` part and sets a default `sideOffset` configuration. #### Usage ```vue ``` #### Implementation ```ts // your-popover.ts export { default as PopoverContent } from 'PopoverContent.vue' export { PopoverRoot as Popover, PopoverTrigger } from 'reka-ui' ``` ```vue ``` --- --- url: /docs/utilities/presence.md description: Manages mounting and unmounting of element with transition support. --- # Presence How is this component different from [Vue Transition](https://vuejs.org/guide/built-ins/transition.html#transition)? A: The biggest difference is it accepts css animation, and control the visibility of element. Presence component provides enhanced control over element mounting/unmounting. It ensures animations and transitions complete before removing elements from the DOM, making it perfect for animated UI components. ## API Reference Read our [Animation Guide](/docs/guides/animation) to learn more about implementing animations with Presence component. ## Example ```vue line=2,4,5 ``` ### Force Mount When you need to ensure content is always rendered regardless of the present state: ```vue ``` --- --- url: /docs/utilities/primitive.md description: >- Compose Reka's functionality onto alternative element types or your own Vue components. --- # Primitive When you are building a component, in some cases you might want to allow user to compose some functionalities onto the underlying element, or alternative element. This is where `Primitive` comes in handy as it expose this capability to the user. ## API Reference ## Usage ### Changing `as` value If you want to change the default element or component being render, you can set the default `as` when defining the props. ```vue ``` ### Render `asChild` Change the default rendered element for the one passed as a child, merging their props and behavior.Read our Composition guide for more details. --- --- url: /docs/components/progress.md description: >- Displays an indicator showing the completion progress of a task, typically displayed as a progress bar. --- # Progress ## Features ## Installation Install the component from your command line. ### Anatomy Import all parts and piece them together. ```vue ``` ## Accessibility Adheres to the [`progressbar` role requirements](https://www.w3.org/WAI/ARIA/apg/patterns/meter). ## API Reference ### Root Contains all of the progress parts. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `getValueLabel` | A function to get the accessible label text in a human-readable format. If not provided, the value label will be read as the numeric value as a percentage of the max value. | `((value: number \| null, max: number) => string)` | No | `isNumber(value) ? `${Math.round((value / max) \* DEFAULT\_MAX)}%` : undefined` | | `getValueText` | A function to get the accessible value text representing the current value in a human-readable format. | `((value: number \| null, max: number) => string)` | No | - | | `max` | The maximum progress value. | `number` | No | `DEFAULT_MAX` | | `modelValue` | The progress value. Can be bind as v-model. | `number \| null` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `update:max` | Event handler called when the max value changes | `[value: number]` | | `update:modelValue` | Event handler called when the progress value changes | `[value: string[]]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `modelValue` | Current input values | `number \| null \| undefined` | ### Indicator Used to show the progress visually. It also makes progress accessible to assistive technologies. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | --- --- url: /docs/components/radio-group.md description: >- A set of checkable buttons—known as radio buttons—where no more than one of the buttons can be checked at a time. --- # RadioGroup ## Features ## Installation Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Root Contains all the parts of a radio group. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `defaultValue` | The value of the radio item that should be checked when initially rendered. Use when you do not need to control the state of the radio items. | `AcceptableValue` | No | - | | `dir` | The reading direction of the combobox when applicable. If omitted, inherits globally from ConfigProvider or assumes LTR (left-to-right) reading mode. | `"ltr" \| "rtl"` | No | - | | `disabled` | When true, prevents the user from interacting with radio items. | `boolean` | No | `false` | | `loop` | When true, keyboard navigation will loop from last item to first, and vice versa. | `boolean` | No | `true` | | `modelValue` | The controlled value of the radio item to check. Can be binded as v-model. | `AcceptableValue` | No | - | | `name` | The name of the field. Submitted with its owning form as part of a name/value pair. | `string` | No | - | | `orientation` | The orientation of the component. | `"vertical" \| "horizontal"` | No | - | | `required` | When true, indicates that the user must set the value before the owning form can be submitted. | `boolean` | No | `false` | **Events** | Name | Description | Type | | --- | --- | --- | | `update:modelValue` | Event handler called when the radio group value changes | `[payload: AcceptableValue]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `modelValue` | Current input values | `null \| string \| number \| bigint \| Record` | ### Item An item in the group that can be checked. An `input` will also render when used within a `form` to ensure events propagate correctly. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | When true, prevents the user from interacting with the radio item. | `boolean` | No | `false` | | `id` | | `string` | No | - | | `name` | The name of the field. Submitted with its owning form as part of a name/value pair. | `string` | No | - | | `required` | When true, indicates that the user must set the value before the owning form can be submitted. | `boolean` | No | - | | `value` | The value given as data when submitted with a name. | `AcceptableValue` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `select` | Event handler called when the user selects a link (via mouse or keyboard). Calling event.preventDefault in this handler will prevent the navigation menu from closing when selecting that link. | `[event: SelectEvent]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `checked` | Current checked state | `boolean` | | `required` | Required state | `boolean` | | `disabled` | Disabled state | `boolean` | ### Indicator Renders when the radio item is in a checked state. You can style this element directly, or you can use it as a wrapper to put an icon into, or both. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"span"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | ## Accessibility Adheres to the [Radio Group WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radiobutton) and uses [roving tabindex](https://www.w3.org/TR/wai-aria-practices-1.2/examples/radio/radio.html) to manage focus movement among radio items. ### Keyboard Interactions --- --- url: /docs/components/range-calendar.md description: Presents a calendar view tailored for selecting date ranges. --- # Range Calendar Alpha ## Features ## Preface The component depends on the [@internationalized/date](https://react-spectrum.adobe.com/internationalized/date/index.html) package, which solves a lot of the problems that come with working with dates and times in JavaScript. We highly recommend reading through the documentation for the package to get a solid feel for how it works, and you'll need to install it in your project to use the date-related components. ## Installation Install the date package. Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Root Contains all the parts of a calendar **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `allowNonContiguousRanges` | When combined with isDateUnavailable, determines whether non-contiguous ranges, i.e. ranges containing unavailable dates, may be selected. | `boolean` | No | `false` | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `calendarLabel` | The accessible label for the calendar | `string` | No | - | | `defaultPlaceholder` | The default placeholder date | `DateValue` | No | - | | `defaultValue` | The default value for the calendar | `DateRange` | No | `{ start: undefined, end: undefined }` | | `dir` | The reading direction of the calendar when applicable. If omitted, inherits globally from ConfigProvider or assumes LTR (left-to-right) reading mode. | `"ltr" \| "rtl"` | No | - | | `disabled` | Whether or not the calendar is disabled | `boolean` | No | `false` | | `disableDaysOutsideCurrentView` | Whether or not to disable days outside the current view. | `boolean` | No | `false` | | `fixedDate` | Which part of the range should be fixed | `"start" \| "end"` | No | - | | `fixedWeeks` | Whether or not to always display 6 weeks in the calendar | `boolean` | No | `false` | | `initialFocus` | If true, the calendar will focus the selected day, today, or the first day of the month depending on what is visible when the calendar is mounted | `boolean` | No | `false` | | `isDateDisabled` | A function that returns whether or not a date is disabled | `Matcher` | No | - | | `isDateHighlightable` | A function that returns whether or not a date is hightable | `Matcher` | No | - | | `isDateUnavailable` | A function that returns whether or not a date is unavailable | `Matcher` | No | - | | `locale` | The locale to use for formatting dates | `string` | No | - | | `maximumDays` | The maximum number of days that can be selected in a range | `number` | No | - | | `maxValue` | The maximum date that can be selected | `DateValue` | No | - | | `minValue` | The minimum date that can be selected | `DateValue` | No | - | | `modelValue` | The controlled selected date range of the calendar. Can be bound as v-model. | `DateRange \| null` | No | - | | `nextPage` | A function that returns the next page of the calendar. It receives the current placeholder as an argument inside the component. | `((placeholder: DateValue) => DateValue)` | No | - | | `numberOfMonths` | The number of months to display at once | `number` | No | `1` | | `pagedNavigation` | This property causes the previous and next buttons to navigate by the number of months displayed at once, rather than one month | `boolean` | No | `false` | | `placeholder` | 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 view | `DateValue` | No | - | | `preventDeselect` | Whether or not to prevent the user from deselecting a date without selecting another date first | `boolean` | No | `false` | | `prevPage` | A function that returns the previous page of the calendar. It receives the current placeholder as an argument inside the component. | `((placeholder: DateValue) => DateValue)` | No | - | | `readonly` | Whether or not the calendar is readonly | `boolean` | No | `false` | | `weekdayFormat` | The format to use for the weekday strings provided via the weekdays slot prop | `"narrow" \| "short" \| "long"` | No | `"narrow"` | | `weekStartsOn` | The day of the week to start the calendar on | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `update:modelValue` | Event handler called whenever the model value changes | `[date: DateRange]` | | `update:placeholder` | Event handler called whenever the placeholder value changes | `[date: DateValue]` | | `update:startValue` | Event handler called whenever the start value changes | `[date: DateValue]` | | `update:validModelValue` | Event handler called whenever there is a new validModel | `[date: DateRange]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `date` | The current date of the placeholder | `DateValue` | | `grid` | The grid of dates | `Grid[]` | | `weekDays` | The days of the week | `string[]` | | `weekStartsOn` | The start of the week | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | | `locale` | The calendar locale | `string` | | `fixedWeeks` | Whether or not to always display 6 weeks in the calendar | `boolean` | | `modelValue` | The current date range | `DateRange` | ### Header Contains the navigation buttons and the heading segments. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Prev Button Calendar navigation button. It navigates the calendar one month/year/decade in the past based on the current calendar view. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `prevPage` | The function to be used for the prev page. Overwrites the prevPage function set on the RangeCalendarRoot. | `((placeholder: DateValue) => DateValue)` | No | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `disabled` | Current disable state | `boolean` | ### Next Button Calendar navigation button. It navigates the calendar one month/year/decade in the future based on the current calendar view. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `nextPage` | The function to be used for the next page. Overwrites the nextPage function set on the RangeCalendarRoot. | `((placeholder: DateValue) => DateValue)` | No | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `disabled` | Current disable state | `boolean` | ### Heading Heading for displaying the current month and year. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `headingValue` | Current month and year | `string` | ### Grid Container for wrapping the calendar grid. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"table"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Grid Head Container for wrapping the grid head. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"thead"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Grid Body Container for wrapping the grid body. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"tbody"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Grid Row Container for wrapping the grid row. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"tr"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Head Cell Container for wrapping the head cell. Used for displaying the week days. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"th"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Cell Container for wrapping the calendar cells. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"td"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `date` | | `DateValue` | Yes | - | ### Cell Trigger Interactable container for displaying the cell dates. Clicking it selects the date. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `day` | | `DateValue` | Yes | - | | `month` | | `DateValue` | Yes | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `dayValue` | Current day | `string` | | `disabled` | Current disable state | `boolean` | | `selected` | Current selected state | `boolean` | | `today` | Current today state | `boolean` | | `outsideView` | Current outside view state | `boolean` | | `outsideVisibleView` | Current outside visible view state | `boolean` | | `unavailable` | Current unavailable state | `boolean` | | `highlighted` | Current highlighted state | `boolean` | | `highlightedStart` | Current highlighted start state | `boolean` | | `highlightedEnd` | Current highlighted end state | `boolean` | | `selectionStart` | Current selection start state | `boolean` | | `selectionEnd` | Current selection end state | `boolean` | ## Accessibility ### Keyboard Interactions --- --- url: /docs/components/rating.md description: >- A star-rating input where the user selects a score, with support for fractional values. --- # Rating ## Features ## Installation Install the component from your command line. ## Anatomy Import all parts and piece them together. `RatingRoot` exposes the list of `items`, and each `RatingItem` exposes the `steps` it is made of, so you render an indicator per step. ```vue ``` ## API Reference ### Root Contains all the parts of a rating and provides the rating state. Renders a [Radio Group](/docs/components/radio-group) under the hood, so it supports form submission and keyboard navigation. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `clearable` | When true, clicking the currently selected rating resets the value to 0. | `boolean` | No | - | | `defaultValue` | The rating value when initially rendered. Use when you do not need to control the state of the rating. | `number` | No | - | | `dir` | The reading direction of the combobox when applicable. If omitted, inherits globally from ConfigProvider or assumes LTR (left-to-right) reading mode. | `"ltr" \| "rtl"` | No | - | | `disabled` | When true, prevents the user from interacting with radio items. | `boolean` | No | - | | `hoverable` | When true, the rating previews the value under the pointer on hover. | `boolean` | No | - | | `length` | The number of rating items to render. | `number` | No | `5` | | `loop` | When true, keyboard navigation will loop from last item to first, and vice versa. | `boolean` | No | - | | `modelValue` | The controlled rating value. Can be bound with v-model. | `number` | No | - | | `name` | The name of the field. Submitted with its owning form as part of a name/value pair. | `string` | No | - | | `orientation` | The orientation of the component. | `"vertical" \| "horizontal"` | No | `"horizontal"` | | `required` | When true, indicates that the user must set the value before the owning form can be submitted. | `boolean` | No | - | | `step` | The granularity each rating item is divided into. | `1 \| 0.5 \| 0.25 \| 0.1` | No | `1` | **Events** | Name | Description | Type | | --- | --- | --- | | `update:modelValue` | Event handler called when the radio group value changes | `[payload: number]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `modelValue` | | `number \| undefined` | | `items` | | `number[]` | ### Item Wraps a single rating value (e.g. a single star). It computes the list of `steps` that compose this item based on the root's `step` prop, exposed via the default slot. Renders a `label` by default. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"label"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `item` | The 1-based index of this item within the rating (e.g. the 3rd star). | `number` | Yes | - | **Slots** | Name | Description | Type | | --- | --- | --- | | `steps` | | `number[]` | ### ItemIndicator The interactive indicator rendered for each step of an item. It reflects whether the step is active based on the current (or hovered) value. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `step` | The step value this indicator represents. | `number` | Yes | - | To render partial steps (for `step` values below `1`), `RatingItemIndicator` exposes the following CSS variables: | CSS Variable | Description | | ---------------------------------- | ------------------------------------------------------------------------------------ | | `--reka-rating-item-step-width` | The width this step should occupy within the item, e.g. `50%` for a half step. | | `--reka-rating-item-step-opacity` | `1` when the step should be visible, `0` otherwise (used to stack overlapping steps). | | `--reka-rating-item-step-z-index` | The stacking order of the step so smaller steps render above larger ones. | A typical fractional indicator clips its width and stacks steps using these variables: ```vue ``` ## Examples ### Fractional rating Use the `step` prop to allow values smaller than `1`. Each `RatingItem` is then split into multiple `steps`, and each step renders its own indicator clipped with the exposed CSS variables. ```vue line=10 ``` ### Clearable Use the `clearable` prop to let users reset the rating to `0` by clicking the currently selected value again. ```vue line=4 ``` ### Hover preview Use the `hoverable` prop to preview the value under the pointer before committing to it. The `RatingItemIndicator` exposes `data-state="active"` for every step at or below the hovered value. ```vue line=4 ``` ### Custom length Use the `length` prop to change how many items are rendered. It defaults to `5`. ```vue line=4 ``` ### Read-only / disabled Use the `disabled` prop to prevent interaction, for example when displaying an average rating. ```vue line=4 ``` ## Accessibility Built on top of the [Radio Group](/docs/components/radio-group) primitive and adheres to the [Radio Group WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio). Provide an accessible label for each step via `aria-label` so screen reader users understand the value each indicator represents. ### Keyboard Interactions --- --- url: /docs/overview/releases.md description: Discover the latest release of Reka UI. --- # Releases [Latest releases on github](https://github.com/unovue/reka-ui/releases) *** ## v2.10 ### ✨ New Features #### Components * **Drawer**: New drawer primitive with swipe gestures, snap points, handle, and nested drawer support Alpha * **Rating**: New component for star-style rating inputs Alpha #### Functionality * **Select**: Added `nullableValue` prop to allow deselecting the current value * **Dialog**: Added `unmountOnHide` prop to control whether content is unmounted when closed * **HoverCard**: Added `enableTouch` prop to enable hover cards on touch devices * **ConfigProvider**: Added `teleportTo` for setting a global default teleport target * **Popper**: Added `dir` prop for `RTL`/`LTR` support * **Tree**: Added `disabled` support for `TreeItem` * **DateField**: Added `stepSnapping` support * **Tabs**: Exposed `--reka-tabs-indicator-thickness` CSS variable #### Developer Experience * **Types**: Improved type inference for `useEmitAsProps` and `useForwardPropsEmits` *** ## v2.9 ### ✨ New Features #### Components * **ColorPicker Suite**: Complete set of color picker components * `ColorArea` - 2D color selection area with thumb * `ColorField` - Text input for entering color values * `ColorSlider` - Slider for adjusting color channels (hue, saturation, etc.) * `ColorSwatch` - Displays a color preview swatch * `ColorSwatchPicker` - Grid of selectable color swatches * **TimeRangeField**: New component for selecting time ranges with start/end inputs * **Autocomplete**: New component for free-form text inputs with optional suggestions (different from Combobox - uses string `modelValue` instead of selected item) * **MonthPicker & YearPicker**: Four new date picker variants * `MonthPicker` - Single month selection * `MonthRangePicker` - Month range selection * `YearPicker` - Single year selection * `YearRangePicker` - Year range selection * **DropdownMenuFilter**: New component for filtering menu items within dropdown menus #### Functionality * **Splitter**: Added support for pixel sizing and constraints (in addition to percentages) * **Checkbox/Switch**: Added support for custom true/false values (not limited to boolean) * **Tooltip**: Added global tooltip content configuration support * **Combobox/Autocomplete**: Added `data-empty` attribute and `hideWhenEmpty` prop to hide dropdown when nothing matches #### Internal (Using it at your own risk) * **Menu**: Now exported via `/internal` path for advanced customization *** ## 2.0 Changes ### ✨ New Features We recommend reviewing the [migration guide](/docs/guides/migration) to make transitioning from v1 to v2 smooth. #### Components * **TimeField**: Implement new TimeField component * **Presence**: Expose component * **ConfigProvider**: Add global config for locale #### Functionality * **Checkbox**: * Support multiple values and more types * Add roving focus props to group * **ToggleGroup**: Support more types * **RadioGroup**: * Support more types * Emit 'select' event when user clicks on item * **Select**: Support different modelValue and option types * **Listbox/Combobox**: * Expose highlight methods * Highlight first item when filter changes * **NavigationMenu**: * Add additional CSS variables for better positioning * Add SSR support * **Collapsible/Accordion**: Add `unmount` prop to help SEO for hidden content #### Developer Experience * **Types**: * Expose useful types * Allow type inference in usePrimitiveElement * **Filtering**: New `useFilter` composable for easy filtering * **Bundle**: Bundle with preserveModules, rollup types dts ### 🔧 Refactors * **Form Components**: * Move visually hidden input element inside root node * **Combobox**: * Use Listbox as base component * Remove ComboboxEmpty * **Popper**: * Allow custom reference el or virtual el * Add position strategy and updateOnLayoutShift props * Rename props for better clarity ### 🐛 Bug Fixes * **NavigationMenu**: Reset position after animation * **Accordion**: Fix SSR animation causing flickers * **Listbox**: Prevent scroll when using pointermove * **Combobox**: * Fix empty state based on search value * Fix initial search not working and virtualizer issues * **Select**: Fix arrow throwing content context injection error * **VisuallyHidden**: Fix not focusable after native form validation ### 🚨 Breaking Changes * **Form Components**: * Rename controlled state to `v-model` * **Popover**: Update aria attributes and remove messy attributes * **Select**: * Fix SSR support * Refactor SelectValue rendering mechanism * **Arrow**: Improve polygon implementation * **Calendar**: Remove deprecated `step` prop --- --- url: /docs/utilities/roving-focus.md description: >- Utility component that implements the roving tabindex method to manage focus between items. --- # Roving Focus Learn more about roving tabindex in [Keyboard Navigation Inside Composite Components](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#x6-6-keyboard-navigation-inside-components) ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Group Contains all the parts of a Roving Focus **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `currentTabStopId` | The controlled value of the current stop item. Can be binded as v-model. | `string \| null` | No | - | | `defaultCurrentTabStopId` | The value of the current stop item. Use when you do not need to control the state of the stop item. | `string` | No | - | | `dir` | The direction of navigation between items. | `"ltr" \| "rtl"` | No | - | | `loop` | Whether keyboard navigation should loop around | `boolean` | No | `false` | | `orientation` | The orientation of the group. Mainly so arrow navigation is done accordingly (left & right vs. up & down) | `"vertical" \| "horizontal"` | No | - | | `preventScrollOnEntryFocus` | When true, will prevent scrolling to the focus item when focused. | `boolean` | No | `false` | **Events** | Name | Description | Type | | --- | --- | --- | | `entryFocus` | Event handler called when container is being focused. Can be prevented. | `[event: Event]` | | `update:currentTabStopId` | | `[value: string \| null]` | **Methods** | Name | Description | Type | | --- | --- | --- | | `getItems` | | `(includeDisabledItem?: boolean) => { ref: HTMLElement; value?: any; }[]` | ### Item The item that would inherit the roving tabindex **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `active` | When true, item will be initially focused. | `boolean` | No | - | | `allowShiftKey` | When true, shift + arrow key will allow focusing on next/previous item. | `boolean` | No | - | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"span"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `focusable` | When false, item will not be focusable. | `boolean` | No | `true` | | `tabStopId` | | `string` | No | - | ## Examples ### Vertical orientation ```vue{2} ``` ### Loop Use `loop` property to enable roving from last item to the first item, and vice versa. ```vue{2} ``` ### Initial focus item Set `active` prop to item to initially focused item. ```vue{4} ``` ### Unfocusable item Set `focusable="false"` prop to item will prevent them from being focused. ```vue{4} ``` ## Accessibility Adheres to the [Keyboard Navigation Inside Composite Components](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#x6-6-keyboard-navigation-inside-components). ### Keyboard Interactions --- --- url: /docs/components/scroll-area.md description: 'Augments native scroll functionality for custom, cross-browser styling.' --- # ScrollArea ## Features ## Installation Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Root Contains all the parts of a scroll area. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `dir` | The reading direction of the combobox when applicable. If omitted, inherits globally from ConfigProvider or assumes LTR (left-to-right) reading mode. | `"ltr" \| "rtl"` | No | - | | `scrollHideDelay` | If type is set to either scroll or hover, this prop determines the length of time, in milliseconds, before the scrollbars are hidden after the user stops interacting with scrollbars. | `number` | No | `600` | | `type` | Describes the nature of scrollbar visibility, similar to how the scrollbar preferences in MacOS control visibility of native scrollbars. auto - means that scrollbars are visible when content is overflowing on the corresponding orientation. always - means that scrollbars are always visible regardless of whether the content is overflowing. scroll - means that scrollbars are visible when the user is scrolling along its corresponding orientation. hover - when the user is scrolling along its corresponding orientation and when the user is hovering over the scroll area. glimpse - a hybrid approach that briefly shows scrollbars when the user enters the scroll area, then hides them until further interaction. | `"scroll" \| "always" \| "hover" \| "auto" \| "glimpse"` | No | `"hover"` | **Methods** | Name | Description | Type | | --- | --- | --- | | `scrollTop` | Scroll viewport to top | `() => void` | | `scrollTopLeft` | Scroll viewport to top-left | `() => void` | ### Viewport The viewport area of the scroll area. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `nonce` | Will add nonce attribute to the style tag which can be used by Content Security Policy. If omitted, inherits globally from ConfigProvider. | `string` | No | - | ### Scrollbar The vertical scrollbar. Add a second `Scrollbar` with an `orientation` prop to enable horizontal scrolling. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | | `orientation` | The orientation of the scrollbar | `"vertical" \| "horizontal"` | No | `"vertical"` | ### Thumb The thumb to be used in `ScrollAreaScrollbar`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Corner The corner where both vertical and horizontal scrollbars meet. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ## Examples ### Custom Scroll Use the exposed `viewport` to modify / or set the scroll position outside default methods ```vue line=4,18 ``` ## Accessibility In most cases, it's best to rely on native scrolling and work with the customization options available in CSS. When that isn't enough, `ScrollArea` provides additional customizability while maintaining the browser's native scroll behavior (as well as accessibility features, like keyboard scrolling). ### Keyboard Interactions Scrolling via keyboard is supported by default because the component relies on native scrolling. Specific keyboard interactions may differ between platforms, so we do not specify them here or add specific event listeners to handle scrolling via key events. --- --- url: /docs/components/select.md description: Displays a list of options for the user to pick from—triggered by a button. --- # Select ## Features ## Installation Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Root Contains all the parts of a Select **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `autocomplete` | Native html input autocomplete attribute. | `string` | No | - | | `by` | Use this to compare objects by a particular field, or pass your own comparison function for complete control over how objects are compared. | `string \| ((a: T, b: T) => boolean)` | No | - | | `defaultOpen` | The open state of the select when it is initially rendered. Use when you do not need to control its open state. | `boolean` | No | - | | `defaultValue` | The value of the select when initially rendered. Use when you do not need to control the state of the Select | `T \| T[]` | No | - | | `dir` | The reading direction of the combobox when applicable. If omitted, inherits globally from ConfigProvider or assumes LTR (left-to-right) reading mode. | `"ltr" \| "rtl"` | No | - | | `disabled` | When true, prevents the user from interacting with Select | `boolean` | No | - | | `modelValue` | The controlled value of the Select. Can be bind as v-model. | `T \| T[]` | No | - | | `multiple` | Whether multiple options can be selected or not. | `boolean` | No | - | | `name` | The name of the field. Submitted with its owning form as part of a name/value pair. | `string` | No | - | | `nullableValue` | The value of the hidden native select option when the model value is nullish. | `string` | No | `""` | | `open` | The controlled open state of the Select. Can be bind as v-model:open. | `boolean` | No | - | | `required` | When true, indicates that the user must set the value before the owning form can be submitted. | `boolean` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `update:modelValue` | Event handler called when the value changes. | `[value: T]` | | `update:open` | Event handler called when the open state of the context menu changes. | `[value: boolean]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `modelValue` | Current input values | `T \| T[] \| undefined` | | `open` | Current open state | `boolean` | ### Trigger The button that toggles the Select The `SelectContent` will position itself by aligning over the trigger. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"button"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | | `boolean` | No | - | | `reference` | The reference (or anchor) element that is being referred to for positioning. If not provided will use the current component as anchor. | `ReferenceElement` | No | - | ### Value The part that reflects the selected value. By default the selected item's text will be rendered. if you require more control, you can instead control the select and pass your own `children`. It should not be styled to ensure correct positioning. An optional `placeholder` prop is also available for when the select has no value. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"span"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `placeholder` | The content that will be rendered inside the SelectValue when no value or defaultValue is set. | `string` | No | `""` | **Slots** | Name | Description | Type | | --- | --- | --- | | `selectedLabel` | | `string[]` | | `modelValue` | | `AcceptableValue \| AcceptableValue[] \| undefined` | ### Icon A small icon often displayed next to the value as a visual affordance for the fact it can be open. By default renders ▼ but you can use your own icon via `asChild` or use `children`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | When true, prevents the user from interacting with the item. | `boolean` | No | - | | `textValue` | Optional text used for typeahead purposes. By default the typeahead behavior will use the .textContent of the SelectItemText part. Use this when the content is complex, or you have non-textual content inside. | `string` | No | - | | `value` | The value given as data when submitted with a name. | `AcceptableValue` | Yes | - | **Events** | Name | Description | Type | | --- | --- | --- | | `select` | Event handler called when the selecting item. It can be prevented by calling event.preventDefault. | `[event: SelectEvent]` | ### Portal When used, portals the content part into the `body`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `defer` | Defer the resolving of a Teleport target until other parts of the application have mounted (requires Vue 3.5.0+) reference | `boolean` | No | - | | `disabled` | Disable teleport and render the component inline reference | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | | `to` | Vue native teleport component prop :to reference | `string \| HTMLElement` | No | - | ### Content The component that pops out when the select is open. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `align` | The preferred alignment against the trigger. May change when collisions occur. | `"start" \| "center" \| "end"` | No | - | | `alignFlip` | Flip alignment when colliding with boundary. May only occur when prioritizePosition is true. | `boolean` | No | - | | `alignOffset` | An offset in pixels from the start or end alignment options. | `number` | No | - | | `arrowPadding` | The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners. | `number` | No | - | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `avoidCollisions` | When true, overrides the side and align preferences to prevent collisions with boundary edges. | `boolean` | No | - | | `bodyLock` | The document.body will be lock, and scrolling will be disabled. | `boolean` | No | - | | `collisionBoundary` | The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. | `Element \| (Element \| null)[] \| null` | No | - | | `collisionPadding` | The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }. | `number \| Partial>` | No | - | | `dir` | The reading direction of the popper content when applicable. If omitted, inherits globally from ConfigProvider or assumes LTR (left-to-right) reading mode. | `"ltr" \| "rtl"` | No | - | | `disableOutsidePointerEvents` | When true, hover/focus/click interactions will be disabled on elements outside the DismissableLayer. Users will need to click twice on outside elements to interact with them: once to close the DismissableLayer, and again to trigger the element. | `boolean` | No | - | | `disableUpdateOnLayoutShift` | Whether to disable the update position for the content when the layout shifted. | `boolean` | No | - | | `forceMount` | Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | `boolean` | No | - | | `hideShiftedArrow` | When true, hides the arrow when it cannot be centered to the reference element. | `boolean` | No | - | | `hideWhenDetached` | Whether to hide the content when the trigger becomes fully occluded. | `boolean` | No | - | | `memoDependencies` | Reactive dependencies that should invalidate the memoized content subtree. | `unknown[]` | No | - | | `position` | The positioning mode to use item-aligned (default) - behaves similarly to a native MacOS menu by positioning content relative to the active item. popper - positions content in the same way as our other primitives, for example Popover or DropdownMenu. | `"popper" \| "item-aligned"` | No | - | | `positionStrategy` | The type of CSS position property to use. | `"fixed" \| "absolute"` | No | - | | `prioritizePosition` | Force content to be position within the viewport. Might overlap the reference element, which may not be desired. | `boolean` | No | - | | `reference` | The custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element. | `ReferenceElement` | No | - | | `side` | The preferred side of the trigger to render against when open. Will be reversed when collisions occur and avoidCollisions is enabled. | `"top" \| "right" \| "bottom" \| "left"` | No | - | | `sideFlip` | Flip to the opposite side when colliding with boundary. | `boolean` | No | - | | `sideOffset` | The distance in pixels from the trigger. | `number` | No | - | | `sticky` | 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. | `"partial" \| "always"` | No | - | | `updatePositionStrategy` | Strategy to update the position of the floating element on every animation frame. | `"always" \| "optimized"` | No | - | **Events** | Name | Description | Type | | --- | --- | --- | | `closeAutoFocus` | Event handler called when auto-focusing on close. Can be prevented. | `[event: Event]` | | `escapeKeyDown` | Event handler called when the escape key is down. Can be prevented. | `[event: KeyboardEvent]` | | `pointerDownOutside` | Event handler called when a pointerdown event happens outside of the DismissableLayer. Can be prevented. | `[event: PointerDownOutsideEvent]` | ### Viewport The scrolling viewport that contains all of the items. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `nonce` | Will add nonce attribute to the style tag which can be used by Content Security Policy. If omitted, inherits globally from ConfigProvider. | `string` | No | - | ### Item The component that contains the select items. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `disabled` | When true, prevents the user from interacting with the item. | `boolean` | No | - | | `textValue` | Optional text used for typeahead purposes. By default the typeahead behavior will use the .textContent of the SelectItemText part. Use this when the content is complex, or you have non-textual content inside. | `string` | No | - | | `value` | The value given as data when submitted with a name. | `AcceptableValue` | Yes | - | **Events** | Name | Description | Type | | --- | --- | --- | | `select` | Event handler called when the selecting item. It can be prevented by calling event.preventDefault. | `[event: SelectEvent]` | ### ItemText The textual part of the item. It should only contain the text you want to see in the trigger when that item is selected. It should not be styled to ensure correct positioning. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"span"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### ItemIndicator Renders when the item is selected. You can style this element directly, or you can use it as a wrapper to put an icon into, or both. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"span"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### ScrollUpButton An optional button used as an affordance to show the viewport overflow as well as functionally enable scrolling upwards. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### ScrollDownButton An optional button used as an affordance to show the viewport overflow as well as functionally enable scrolling downwards. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Group Used to group multiple items. use in conjunction with `SelectLabel` to ensure good accessibility via automatic labelling. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Label Used to render the label of a group. It won't be focusable using arrow keys. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `for` | | `string` | No | - | ### Separator Used to visually separate items in the Select **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Arrow An optional arrow element to render alongside the content. This can be used to help visually link the trigger with the `SelectContent`. Must be rendered inside `SelectContent`. Only available when `position` is set to `popper`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"svg"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `height` | The height of the arrow in pixels. | `number` | No | `5` | | `rounded` | When true, render the rounded version of arrow. Do not work with as/asChild | `boolean` | No | - | | `width` | The width of the arrow in pixels. | `number` | No | `10` | ## Examples ### Change the positioning mode By default, `Select` will behave similarly to a native MacOS menu by positioning `SelectContent` relative to the active item. If you would prefer an alternative positioning approach similar to `Popover` or `DropdownMenu` then you can set `position` to `popper` and make use of additional alignment options such as `side`, `sideOffset` and more. ```vue line=20-23 // index.vue ``` ### Constrain the content size When using `position="popper"` on `SelectContent`, you may want to constrain the width of the content so that it matches the trigger width. You may also want to constrain its height to not exceed the viewport. We expose several CSS custom properties such as `--reka-select-trigger-width` and `--reka-select-content-available-height` to support this. Use them to constrain the content dimensions. ```vue line=21 // index.vue ``` ```css line=3,4 /* styles.css */ .SelectContent { width: var(--reka-select-trigger-width); max-height: var(--reka-select-content-available-height); } ``` ### With disabled items You can add special styles to disabled items via the `data-disabled` attribute. ```vue line=23-24 // index.vue ``` ```css line=2 /* styles.css */ .SelectItem[data-disabled] { color: "gainsboro"; } ``` ### With a placeholder You can use the `placeholder` prop on `Value` for when the select has no value. There's also a `data-placeholder` attribute on `Trigger` to help with styling. ```vue line=19,20 // index.vue ``` ```css line=2 /* styles.css */ .SelectTrigger[data-placeholder] { color: "gainsboro"; } ``` ### With separators Use the `Separator` part to add a separator between items. ```vue line=10 ``` ### With grouped items Use the `Group` and `Label` parts to group items in a section. ```vue line=7,8,12 ``` ### With complex items You can use custom content in your items. ```vue line=23 ``` ### Controlling the value displayed in the trigger By default the trigger display the selected item's text (no longer automatically render `ItemText`'s content like in v1). If you need to render other than plain text, you can control the component using `v-model` props (or accessing `SelectValue`'s slotProps) and passing `slot` to `SelectValue`. Remember to make sure what you put in there is accessible. ```vue line=2,4,10-12 ``` ### With custom scrollbar The native scrollbar is hidden by default as we recommend using the `ScrollUpButton` and `ScrollDownButton` parts for the best UX. If you do not want to use these parts, compose your select with our [Scroll Area](scroll-area) primitive. ```vue line=25,27,32-34 // index.vue ``` ```css /* styles.css */ .ScrollAreaRoot { width: 100%; height: 100%; } .ScrollAreaViewport { width: 100%; height: 100%; } .ScrollAreaScrollbar { width: 4px; padding: 5px 2px; } .ScrollAreaThumb { background: rgba(0, 0, 0, 0.3); borderradius: 3px; } ``` ## Accessibility Adheres to the [ListBox WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox). See the W3C [Select-Only Combobox](https://www.w3.org/TR/wai-aria-practices/examples/combobox/combobox-select-only.html) example for more information. ### Keyboard Interactions ### Labelling Use our [Label](label) component in order to offer a visual and accessible label for the Select ```vue line=19,22,26,28 ``` ## Custom APIs Create your own API by abstracting the primitive parts into your own component. ### Abstract down to `Select` and `SelectItem` This example abstracts most of the parts. #### Usage ```vue ``` #### Implementation ```ts // your-select.ts export { default as Select } from 'Select.vue' export { default as SelectItem } from 'SelectItem.vue' ``` ```vue ``` ```vue ``` --- --- url: /docs/components/separator.md description: Visually or semantically separates content. --- # Separator ## Features ## Installation Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Root The separator. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"div"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `decorative` | Whether or not the component is purely decorative. When true, accessibility-related attributes are updated so that that the rendered element is removed from the accessibility tree. | `boolean` | No | - | | `orientation` | Orientation of the component. Either vertical or horizontal. Defaults to horizontal. | `"vertical" \| "horizontal"` | No | `"horizontal"` | ## Accessibility Adheres to the [`separator` role requirements](https://www.w3.org/TR/wai-aria-1.2/#separator). --- --- url: /docs/guides/server-side-rendering.md description: Reka UI can be rendered on the server. --- # Server side rendering ## Overview Server side rendering or `SSR`, is a technique used to render components to HTML on the server, as opposed to rendering them only on the client. Static rendering is another similar approach. Instead it pre-renders pages to HTML at build time rather than on each request. You should be able to use all of our primitives with both approaches, for example with [Nuxt.js](https://nuxt.com/). ## Nuxt Hydration issue (Vue < 3.5) Reka UI offers a [Nuxt module](/docs/overview/installation.html#nuxt-modules) that supports auto importing components. However, if you are using Vue < 3.5, minor hydration issues might arise because as of vue <= 3.4 there is [currently no way](https://github.com/vuejs/rfcs/discussions/557) to ensure consistent DOM element `id` between the client and server renders. This is something that Reka UI relies on. As a temporary workaround, we expose a way to allow Nuxt (with version > `3.10`) inject it's `useId` implementation to `reka-ui`. To provide a custom `useId` implementation, please follow this [guide](/docs/utilities/config-provider.html#hydration-issue-vue-3-5). --- --- url: /docs/components/slider.md description: An input where the user selects a value from within a given range. --- # Slider ## Features ## Installation Install the component from your command line. ## Anatomy Import all parts and piece them together. ```vue ``` ## API Reference ### Root Contains all the parts of a slider. It will render an `input` for each thumb when used within a `form` to ensure events propagate correctly. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"span"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | | `defaultValue` | The value of the slider when initially rendered. Use when you do not need to control the state of the slider. | `number[]` | No | `[0]` | | `dir` | The reading direction of the combobox when applicable. If omitted, inherits globally from ConfigProvider or assumes LTR (left-to-right) reading mode. | `"ltr" \| "rtl"` | No | - | | `disabled` | When true, prevents the user from interacting with the slider. | `boolean` | No | `false` | | `inverted` | Whether the slider is visually inverted. | `boolean` | No | `false` | | `max` | The maximum value for the range. | `number` | No | `100` | | `min` | The minimum value for the range. | `number` | No | `0` | | `minStepsBetweenThumbs` | The minimum permitted steps between multiple thumbs. | `number` | No | `0` | | `modelValue` | The controlled value of the slider. Can be bind as v-model. | `number[] \| null` | No | - | | `name` | The name of the field. Submitted with its owning form as part of a name/value pair. | `string` | No | - | | `orientation` | The orientation of the slider. | `"vertical" \| "horizontal"` | No | `"horizontal"` | | `required` | When true, indicates that the user must set the value before the owning form can be submitted. | `boolean` | No | - | | `step` | The stepping interval. | `number` | No | `1` | | `thumbAlignment` | The alignment of the slider thumb. contain: thumbs will be contained within the bounds of the track. overflow: thumbs will not be bound by the track. No extra offset will be added. | `"contain" \| "overflow"` | No | `"contain"` | **Events** | Name | Description | Type | | --- | --- | --- | | `update:modelValue` | Event handler called when the slider value changes | `[payload: number[]]` | | `valueCommit` | Event handler called when the value changes at the end of an interaction. Useful when you only need to capture a final value e.g. to update a backend service. | `[payload: number[]]` | **Slots** | Name | Description | Type | | --- | --- | --- | | `modelValue` | Current slider values | `number[] \| null` | ### Track The track that contains the `SliderRange`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"span"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Range The range part. Must live inside `SliderTrack`. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"span"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ### Thumb A draggable thumb. You can render multiple thumbs. **Props** | Name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `as` | The element or component this component should render as. Can be overwritten by asChild. | `AsTag \| Component` | No | `"span"` | | `asChild` | Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | `boolean` | No | - | ## Examples ### Vertical orientation Use the `orientation` prop to create a vertical slider. ```vue line=10 // index.vue ``` ```css line=7,18,26 /* styles.css */ .SliderRoot { position: relative; display: flex; align-items: center; } .SliderRoot[data-orientation="vertical"] { flex-direction: column; width: 20px; height: 100px; } .SliderTrack { position: relative; flex-grow: 1; background-color: grey; } .SliderTrack[data-orientation="vertical"] { width: 3px; } .SliderRange { position: absolute; background-color: black; } .SliderRange[data-orientation="vertical"] { width: 100%; } .SliderThumb { display: block; width: 20px; height: 20px; background-color: black; } ``` ### Create a range Add multiple thumbs and values to create a range slider. ```vue line=7,11-12 // index.vue ``` ### Define step size Use the `step` prop to increase the stepping interval. ```vue line=9 // index.vue ``` ### Prevent thumb overlap Use `minStepsBetweenThumbs` to avoid thumbs with equal values. ```vue line=10 // index.vue ``` ## Accessibility Adheres to the [Slider WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slidertwothumb). ### Keyboard Interactions #### Inverted sliders When the slider is inverted, some controls are inverted as well, depending on the orientation. * When the slider is horizontal (the default), ArrowRight, ArrowLeft, Home, and End are inverted. * When the slider is vertical, ArrowUp, ArrowDown, PageUp, PageDown, Shift + ArrowUp, and Shift + ArrowDown are inverted. ## Custom APIs Create your own API by abstracting the primitive parts into your own component. ### Abstract all parts This example abstracts all of the `Slider` parts so it can be used as a self closing element. #### Usage ```vue ``` #### Implementation ```ts // your-slider.ts export { default as Slider } from 'Slider.vue' ``` ```vue ``` ## Caveats ### Mouse events are not fired Because of [a limitation](https://github.com/unovue/reka-ui/blob/v2/packages/core/src/Slider/SliderImpl.vue#L48-L49) we faced during implementation, the following example won't work as expected and the `@mousedown` and `@mousedown` event handlers won't be fired: ```vue ``` We recommend using pointer events instead (eg. `@pointerdown`, `@pointerup`). Regardless of the above limitation, these events are better suited for cross-platform/device handling as they are fired for all pointer input types (mouse, touch, pen, etc.). --- --- url: /docs/utilities/slot.md description: Merges its props onto its immediate child. --- # Slot How is this component different from [Vue native slot](https://vuejs.org/guide/components/slots.html)? A: The biggest different is how it handles the `attributes` assigned to it. Native slot treat any binded value as [Scoped Slots](https://vuejs.org/guide/components/slots.html#scoped-slots), where the values will be exposed to the parent template and be consumed. But Reka UI's slot behave differently, it would merge all the assigned attributes onto it's immediate child. ## Example Say we want to assign an `id` attribute to whatever component/element that was rendered, but Native slot will convert it into a scoped slot, and you will need to assign that id manually. ```vue