A set of completely unstyled, fully accessible UI components for Vue 3, designed to integrate
beautifully with Tailwind CSS.
## Installation
Please note that **this library only supports Vue 3**.
```sh
# npm
npm install @headlessui/vue
# Yarn
yarn add @headlessui/vue
```
## Components
_This project is still in early development. New components will be added regularly over the coming months._
- [Menu Button (Dropdown)](#menu-button-dropdown)
- [Listbox (Select)](#listbox-select)
- [Switch (Toggle)](#switch-toggle)
### Roadmap
This project is still in early development, but the plan is to build out all of the primitives we need to provide interactive Vue examples of all of the components included in [Tailwind UI](https://tailwindui.com), the commercial component directory that helps us fund the development of our open-source work like [Tailwind CSS](https://tailwindcss.com).
This includes things like:
- Modals
- Tabs
- Slide-overs
- Mobile menus
- Accordions
...and more in the future.
We'll be continuing to develop new components on an on-going basis, with a goal of reaching a pretty fleshed out v1.0 by the end of the year.
---
## Menu Button (Dropdown)
[View live demo on CodeSandbox](https://codesandbox.io/s/headlessuivue-menu-example-70br3?file=/src/App.vue)
The `Menu` component and related child components are used to quickly build custom dropdown components that are fully accessible out of the box, including correct ARIA attribute management and robust keyboard navigation support.
- [Basic example](#basic-example)
- [Styling](#styling)
- [Transitions](#transitions)
- [Component API](#component-api)
### Basic example
Menu Buttons are built using the `Menu`, `MenuButton`, `MenuItems`, and `MenuItem` components.
The `MenuButton` will automatically open/close the `MenuItems` when clicked, and when the menu is open, the list of items receives focus and is automatically navigable via the keyboard.
```vue
```
### Styling the active item
This is a headless component so there are no styles included by default. Instead, the components expose useful information via [scoped slots](https://v3.vuejs.org/guide/component-slots.html#scoped-slots) that you can use to apply the styles you'd like to apply yourself.
To style the active `MenuItem` you can read the `active` slot prop, which tells you whether or not that menu item is the item that is currently focused via the mouse or keyboard.
You can use this state to conditionally apply whatever active/focus styles you like, for instance a blue background like is typical in most operating systems.
```vue
```
### Showing/hiding the menu
By default, your `MenuItems` instance will be shown/hidden automatically based on the internal `open` state tracked within the `Menu` component itself.
```vue
```
If you'd rather handle this yourself (perhaps because you need to add an extra wrapper element for one reason or another), you can add a `static` prop to the `MenuItems` instance to tell it to always render, and inspect the `open` slot prop provided by the `Menu` to control which element is shown/hidden yourself.
```vue
```
### Disabling an item
Use the `disabled` prop to disable a `MenuItem`. This will make it unselectable via keyboard navigation, and it will be skipped when pressing the up/down arrows.
```vue
```
### Transitions
To animate the opening/closing of the menu panel, use Vue's built-in `transition` component. All you need to do is wrap your `MenuItems` instance in a `` element and the transition will be applied automatically.
```vue
```
### Rendering additional content
The `Menu` component is not limited to rendering only its related subcomponents. You can render anything you like within a menu, which gives you complete control over exactly what you are building.
For example, if you'd like to add a little header section to the menu with some extra information in it, just render an extra `div` with your content in it.
```vue
```
Note that only `MenuItem` instances will be navigable via the keyboard.
### Rendering a different element for a component
By default, the `Menu` and its subcomponents each render a default element that is sensible for that component.
For example, `MenuButton` renders a `button` by default, and `MenuItems` renders a `div`. `Menu` and `MenuItem` interestingly _do not render an extra element_, and instead render their children directly by default.
This is easy to change using the `as` prop, which exists on every component.
```vue
```
To tell an element to render its children directly with no wrapper element, use `as="template"`.
```vue
```
### Component API
#### Menu
```vue
```
##### Props
| Prop | Type | Default | Description |
| ---- | ------------------- | --------------------------------- | ----------------------------------------------------- |
| `as` | String \| Component | `template` _(no wrapper element_) | The element or component the `Menu` should render as. |
##### Slot props
| Prop | Type | Description |
| ------ | ------- | -------------------------------- |
| `open` | Boolean | Whether or not the menu is open. |
#### MenuButton
```vue
More options
```
##### Props
| Prop | Type | Default | Description |
| ---- | ------------------- | -------- | ----------------------------------------------------------- |
| `as` | String \| Component | `button` | The element or component the `MenuButton` should render as. |
##### Slot props
| Prop | Type | Description |
| ------ | ------- | -------------------------------- |
| `open` | Boolean | Whether or not the menu is open. |
#### MenuItems
```vue
```
##### Props
| Prop | Type | Default | Description |
| --------- | ------------------- | ------- | --------------------------------------------------------------------------------- |
| `as` | String \| Component | `div` | The element or component the `MenuItems` should render as. |
| `static` | Boolean | `false` | Whether the element should ignore the internally managed open/closed state. |
| `unmount` | Boolean | `true` | Whether the element should be unmounted or hidden based on the open/closed state. |
##### Slot props
| Prop | Type | Description |
| ------ | ------- | -------------------------------- |
| `open` | Boolean | Whether or not the menu is open. |
#### MenuItem
```vue
```
##### Props
| Prop | Type | Default | Description |
| ---------- | ------------------- | --------------------------------- | ------------------------------------------------------------------------------------- |
| `as` | String \| Component | `template` _(no wrapper element)_ | The element or component the `MenuItem` should render as. |
| `disabled` | Boolean | `false` | Whether or not the item should be disabled for keyboard navigation and ARIA purposes. |
##### Slot props
| Prop | Type | Description |
| ---------- | ------- | ---------------------------------------------------------------------------------- |
| `active` | Boolean | Whether or not the item is the active/focused item in the list. |
| `disabled` | Boolean | Whether or not the item is the disabled for keyboard navigation and ARIA purposes. |
## Listbox (Select)
[View live demo on CodeSandbox](https://codesandbox.io/s/headlessuivue-listbox-example-mi67g?file=/src/App.vue)
The `Listbox` component and related child components are used to quickly build custom listbox components that are fully accessible out of the box, including correct ARIA attribute management and robust keyboard navigation support.
- [Basic example](#basic-example-2)
- [Styling the active and selected option](#styling-the-active-and-selected-option)
- [Showing/hiding the listbox](#showinghiding-the-listbox)
- [Using a custom label](#using-a-custom-label)
- [Disabling an option](#disabling-an-option)
- [Transitions](#transitions-1)
- [Rendering additional content](#rendering-additional-content-1)
- [Rendering a different element for a component](#rendering-a-different-element-for-a-component-1)
- [Component API](#component-api-2)
### Basic example
Listboxes are built using the `Listbox`, `ListboxButton`, `ListboxOptions`, `ListboxOption` and `ListboxLabel` components.
The `ListboxButton` will automatically open/close the `ListboxOptions` when clicked, and when the menu is open, the list of items receives focus and is automatically navigable via the keyboard.
```vue
{{ selectedPerson.name }}
{{ person.name }}
```
### Styling the active and selected option
This is a headless component so there are no styles included by default. Instead, the components expose useful information via [scoped slots](https://v3.vuejs.org/guide/component-slots.html#scoped-slots) that you can use to apply the styles you'd like to apply yourself.
To style the active `ListboxOption` you can read the `active` slot prop, which tells you whether or not that listbox option is the option that is currently focused via the mouse or keyboard.
To style the selected `ListboxOption` you can read the `selected` slot prop, which tells you whether or not that listbox option is the option that is currently the `value` passed to the `Listbox`.
You can use this state to conditionally apply whatever active/focus styles you like, for instance a blue background like is typical in most operating systems. For the selected state, you might conditionally render a checkmark next to the seleted option.
```vue
{{ selectedPerson.name }}
{{ person.name }}
```
### Using a custom label
By default the `Listbox` will use the button contents as the label for screenreaders. However you can also render a custom `ListboxLabel` which will be automatically linked to the listbox with a generated ID.
```vue
Country:{country}AustraliaBelgiumCanadaEngland
```
### Showing/hiding the listbox
By default, your `ListboxOptions` instance will be shown/hidden automatically based on the internal `open` state tracked within the `Listbox` component itself.
```vue
{{ person.name }}
{{ person.name }}
```
If you'd rather handle this yourself (perhaps because you need to add an extra wrapper element for one reason or another), you can add a `static` prop to the `ListboxOptions` instance to tell it to always render, and inspect the `open` slot prop provided by the `Listbox` to control which element is shown/hidden yourself.
```vue
{{ person.name }}
{{ person.name }}
```
### Disabling an option
Use the `disabled` prop to disable a `ListboxOption`. This will make it unselectable via keyboard navigation, and it will be skipped when pressing the up/down arrows.
```vue
{{ selectedPerson.name }}{{ person.name }}
```
### Transitions
To animate the opening/closing of the menu panel, use Vue's built-in `transition` component. All you need to do is wrap your `ListboxOptions` instance in a `` element and the transition will be applied automatically.
```vue
{{ selectedPerson.name }}
{{ person.name }}
```
### Rendering a different element for a component
By default, the `Listbox` and its subcomponents each render a default element that is sensible for that component.
For example, `ListboxLabel` renders a `label` by default, `ListboxButton` renders a `button` by default, `ListboxOptions` renders a `ul` and `ListboxOption` renders a `li` by default. `Listbox` interestingly _does not render an extra element_, and instead renders its children directly by default.
This is easy to change using the `as` prop, which exists on every component.
```vue
{{ selectedPerson.name }}
{{ person.name }}
```
To tell an element to render its children directly with no wrapper element, use `as="template"`.
```vue
{{ person.name }}
```
### Component API
#### Listbox
```vue
{{ selectedPerson.name }}
{{ person.name }}
```
##### Props
| Prop | Type | Default | Description |
| --------- | ------------------- | --------------------------------- | -------------------------------------------------------- |
| `as` | String \| Component | `template` _(no wrapper element_) | The element or component the `Listbox` should render as. |
| `v-model` | `T` | | The selected value. |
##### Slot props
| Prop | Type | Description |
| ------ | ------- | ----------------------------------- |
| `open` | Boolean | Whether or not the listbox is open. |
#### ListboxButton
```vue
{{ selectedPerson.name }}
```
##### Props
| Prop | Type | Default | Description |
| ---- | ------------------- | -------- | -------------------------------------------------------------- |
| `as` | String \| Component | `button` | The element or component the `ListboxButton` should render as. |
##### Slot props
| Prop | Type | Description |
| ------ | ------- | ----------------------------------- |
| `open` | Boolean | Whether or not the listbox is open. |
#### ListboxLabel
```vue
Enable notifications
```
##### Props
| Prop | Type | Default | Description |
| ---- | ------------------- | ------- | ------------------------------------------------------------- |
| `as` | String \| Component | `label` | The element or component the `ListboxLabel` should render as. |
#### ListboxOptions
```vue
```
##### Props
| Prop | Type | Default | Description |
| --------- | ------------------- | ------- | --------------------------------------------------------------------------------- |
| `as` | String \| Component | `ul` | The element or component the `ListboxOptions` should render as. |
| `static` | Boolean | `false` | Whether the element should ignore the internally managed open/closed state. |
| `unmount` | Boolean | `true` | Whether the element should be unmounted or hidden based on the open/closed state. |
##### Slot props
| Prop | Type | Description |
| ------ | ------- | ----------------------------------- |
| `open` | Boolean | Whether or not the listbox is open. |
#### ListboxOption
```vue
Option A
```
##### Props
| Prop | Type | Default | Description |
| ---------- | ------------------- | ------- | --------------------------------------------------------------------------------------- |
| `as` | String \| Component | `li` | The element or component the `ListboxOption` should render as. |
| `value` | `T` | | The option value. |
| `disabled` | Boolean | `false` | Whether or not the option should be disabled for keyboard navigation and ARIA purposes. |
##### Slot props
| Prop | Type | Description |
| ---------- | ------- | ------------------------------------------------------------------------------------ |
| `active` | Boolean | Whether or not the option is the active/focused option in the list. |
| `selected` | Boolean | Whether or not the option is the selected option in the list. |
| `disabled` | Boolean | Whether or not the option is the disabled for keyboard navigation and ARIA purposes. |
## Switch (Toggle)
[View live demo on CodeSandbox](https://codesandbox.io/s/headlessuivue-switch-example-8ycp6?file=/src/App.vue)
The `Switch` component and related child components are used to quickly build custom switch/toggle components that are fully accessible out of the box, including correct ARIA attribute management and robust keyboard support.
- [Basic example](#basic-example-2)
- [Using a custom label](#using-a-custom-label-1)
- [Component API](#component-api-2)
### Basic example
Switches are built using the `Switch` component. Optionally you can also use the `SwitchGroup` and `SwitchLabel` components.
```vue
```
### Using a custom label
By default the `Switch` will use the contents as the label for screenreaders. If you need more control, you can render a `SwitchLabel` outside of the `Switch`, as long as both the switch and label are within a parent `SwitchGroup`.
Clicking the label will toggle the switch state, like you'd expect from a native checkbox.
```vue
Enable notifications
```
### Component API
#### Switch
```html
Enable notifications
```
##### Props
| Prop | Type | Default | Description |
| --------- | ------------------- | -------- | ------------------------------------------------------- |
| `as` | String \| Component | `button` | The element or component the `Switch` should render as. |
| `v-model` | `T` | | The switch value. |
##### Slot props
| Prop | Type | Description |
| --------- | ------- | ------------------------------------- |
| `checked` | Boolean | Whether or not the switch is checked. |
#### SwitchLabel
```html
Enable notifications
```
##### Props
| Prop | Type | Default | Description |
| ---- | ------------------- | ------- | ------------------------------------------------------------ |
| `as` | String \| Component | `label` | The element or component the `SwitchLabel` should render as. |
#### SwitchGroup
```html
Enable notifications
```
##### Props
| Prop | Type | Default | Description |
| ---- | ------------------- | --------------------------------- | ------------------------------------------------------------ |
| `as` | String \| Component | `template` _(no wrapper element)_ | The element or component the `SwitchGroup` should render as. |
