diff --git a/README.md b/README.md index 580949e..d916dde 100644 --- a/README.md +++ b/README.md @@ -7,9 +7,25 @@ beautifully with Tailwind CSS.

+--- + +## Documentation + +For full documentation, visit [headlessui.dev](https://headlessui.dev). + ## Packages | Name | Version | Downloads | | :------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------: | | [`@headlessui/react`](https://github.com/tailwindlabs/headlessui/tree/main/packages/%40headlessui-react) | [![npm version](https://img.shields.io/npm/v/@headlessui/react.svg)](https://www.npmjs.com/package/@headlessui/react) | [![npm downloads](https://img.shields.io/npm/dt/@headlessui/react.svg)](https://www.npmjs.com/package/@headlessui/react) | | [`@headlessui/vue`](https://github.com/tailwindlabs/headlessui/tree/main/packages/%40headlessui-vue) | [![npm version](https://img.shields.io/npm/v/@headlessui/vue.svg)](https://www.npmjs.com/package/@headlessui/vue) | [![npm downloads](https://img.shields.io/npm/dt/@headlessui/vue.svg)](https://www.npmjs.com/package/@headlessui/vue) | + +## Community + +For help, discussion about best practices, or any other conversation that would benefit from being searchable: + +[Discuss Headless UI on GitHub](https://github.com/tailwindlabs/tailwindcss/discussions) + +For casual chit-chat with others using the library: + +[Join the Tailwind CSS Discord Server](https://discord.gg/7NF8GNe) diff --git a/packages/@headlessui-react/README.md b/packages/@headlessui-react/README.md index 032c01e..3fddf1f 100644 --- a/packages/@headlessui-react/README.md +++ b/packages/@headlessui-react/README.md @@ -10,7 +10,7 @@

Total Downloads Latest Release - License + License

## Installation @@ -23,30 +23,17 @@ npm install @headlessui/react yarn add @headlessui/react ``` -## Components +## Documentation -_This project is still in early development. New components will be added regularly over the coming months._ +For full documentation, visit [headlessui.dev](https://headlessui.dev/react). -- [Transition](./src/components/transitions/README.md) -- [Menu Button (Dropdown)](./src/components/menu/README.md) -- [Listbox (Select)](./src/components/listbox/README.md) -- [Switch (Toggle)](./src/components/switch/README.md) -- [Disclosure](./src/components/disclosure/README.md) -- [FocusTrap](./src/components/focus-trap/README.md) -- [Portal](./src/components/portal/README.md) -- [Dialog](./src/components/dialog/README.md) -- [Popover](./src/components/popover/README.md) -- [Radio Group](./src/components/radio-group/README.md) +## Community -### Roadmap +For help, discussion about best practices, or any other conversation that would benefit from being searchable: -This project is still in early development, but the plan is to build out all of the primitives we need to provide interactive React 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). +[Discuss Headless UI on GitHub](https://github.com/tailwindlabs/tailwindcss/discussions) -This includes things like: +For casual chit-chat with others using the library: -- Tabs -- Accordions +[Join the Tailwind CSS Discord Server](https://discord.gg/7NF8GNe) -...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. diff --git a/packages/@headlessui-react/src/components/dialog/README.md b/packages/@headlessui-react/src/components/dialog/README.md deleted file mode 100644 index 36e7551..0000000 --- a/packages/@headlessui-react/src/components/dialog/README.md +++ /dev/null @@ -1,155 +0,0 @@ -## Dialog - -- [Installation](#installation) -- [Basic example](#basic-example) -- [Component API](#component-api) - -This component can be used to render content inside a Dialog/Modal. This contains a ton of features: - -1. Renders inside a `Portal` -2. Controlled component -3. Uses `FocusTrap` with its features (Focus first focusable element, `autoFocus` or `initialFocus` ref) - > **NOTE:** This component will throw when there are no focusable elements. - > This is an accessibility feature. At least try to provide a close button or - > similar so that users don't get stuck. -4. Adds a scroll lock -5. Prevents content jumps by faking your scrollbar width -6. Marks other elements as `inert` (hides other elements from screen readers) -7. Closes on `escape` -8. Closes on click outside -9. Once the Dialog becomes hidden (e.g.: `md:hidden`) it will also trigger the `onClose` - -### Installation - -```sh -# npm -npm install @headlessui/react - -# Yarn -yarn add @headlessui/react -``` - -### Basic example - -```jsx -import { useState } from 'react' -import { Dialog } from '@headlessui/react' - -function Example() { - let [isOpen, setIsOpen] = useState(true) - - return ( - - - - Deactivate account - This will permanently deactivate your account - -

- Are you sure you want to deactivate your account? All of your data will be permanently - removed. This action cannot be undone. -

- - - - - ) -} -``` - -### Component API - -#### Dialog - -```jsx -import { useState } from 'react' -import { Dialog } from '@headlessui/react' - -function Example() { - let [isOpen, setIsOpen] = useState(true) - - return ( - - - - Deactivate account - This will permanently deactivate your account - -

- Are you sure you want to deactivate your account? All of your data will be permanently - removed. This action cannot be undone. -

- - - - - ) -} -``` - -##### Props - -| Prop | Type | Default | Description | -| :------------- | :--------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------- | -| `open` | Boolean | / | Wether the `Dialog` is open or not. | -| `onClose` | Function | / | Called when the `Dialog` should close. For convenience we pass in a `onClose(false)` so that you can use: `onClose={setIsOpen}`. | -| `initialFocus` | React.MutableRefObject | / | A ref to an element that should receive focus first. | -| `as` | String \| Component | `div` | The element or component the `Dialog` 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. | - -> **note**: `static` and `unmount` can not be used at the same time. You will get a TypeScript error if you try to do it. - -##### Render prop object - -| Prop | Type | Description | -| :----- | :------ | :--------------------------------- | -| `open` | Boolean | Whether or not the dialog is open. | - -#### Dialog.Overlay - -This can be used to create an overlay for your Dialog component. Clicking on the overlay will close the Dialog. - -##### Props - -| Prop | Type | Default | Description | -| :--- | :------------------ | :------ | :-------------------------------------------------------------- | -| `as` | String \| Component | `div` | The element or component the `Dialog.Overlay` should render as. | - -##### Render prop object - -| Prop | Type | Description | -| :----- | :------ | :------------------------------------- | -| `open` | Boolean | Whether or not the dialog is open. | - -#### Dialog.Title - -This is the title for your Dialog. When this is used, it will set the `aria-labelledby` on the Dialog. - -##### Props - -| Prop | Type | Default | Description | -| :--- | :------------------ | :------ | :------------------------------------------------------------ | -| `as` | String \| Component | `h2` | The element or component the `Dialog.Title` should render as. | - -##### Render prop object - -| Prop | Type | Description | -| :----- | :------ | :------------------------------------- | -| `open` | Boolean | Whether or not the dialog is open. | - -#### Dialog.Description - -This is the description for your Dialog. When this is used, it will set the `aria-describedby` on the Dialog. - -##### Props - -| Prop | Type | Default | Description | -| :--- | :------------------ | :------ | :------------------------------------------------------------------ | -| `as` | String \| Component | `p` | The element or component the `Dialog.Description` should render as. | - -##### Render prop object - -| Prop | Type | Description | -| :----- | :------ | :------------------------------------- | -| `open` | Boolean | Whether or not the dialog is open. | diff --git a/packages/@headlessui-react/src/components/disclosure/README.md b/packages/@headlessui-react/src/components/disclosure/README.md deleted file mode 100644 index a7404ee..0000000 --- a/packages/@headlessui-react/src/components/disclosure/README.md +++ /dev/null @@ -1,81 +0,0 @@ -## Disclosure - -A component for showing/hiding content. - -- [Installation](#installation) -- [Basic example](#basic-example) -- [Component API](#component-api) - -### Installation - -```sh -# npm -npm install @headlessui/react - -# Yarn -yarn add @headlessui/react -``` - -### Basic example - -```jsx - - Toggle - Contents - -``` - -### Component API - -#### Disclosure - -```jsx - - Toggle - Contents - -``` - -##### Props - -| Prop | Type | Default | Description | -| :--- | :------------------ | :-------------------------------------- | :---------------------------------------------------------- | -| `as` | String \| Component | `React.Fragment` _(no wrapper element_) | The element or component the `Disclosure` should render as. | - -##### Render prop object - -| Prop | Type | Description | -| :----- | :------ | :------------------------------------- | -| `open` | Boolean | Whether or not the disclosure is open. | - -#### Disclosure.Button - -##### Props - -| Prop | Type | Default | Description | -| :--- | :------------------ | :------- | :----------------------------------------------------------------- | -| `as` | String \| Component | `button` | The element or component the `Disclosure.Button` should render as. | - -##### Render prop object - -| Prop | Type | Description | -| :----- | :------ | :------------------------------------- | -| `open` | Boolean | Whether or not the disclosure is open. | - -#### Disclosure.Panel - -##### Props - -| Prop | Type | Default | Description | -| :-------- | :------------------ | :------ | :-------------------------------------------------------------------------------- | -| `as` | String \| Component | `div` | The element or component the `Disclosure.Panel` 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. | - -> **note**: `static` and `unmount` can not be used at the same time. You will get a TypeScript error if you try to do it. - -##### Render prop object - -| Prop | Type | Description | -| :----- | :------ | :------------------------------------- | -| `open` | Boolean | Whether or not the disclosure is open. | diff --git a/packages/@headlessui-react/src/components/focus-trap/README.md b/packages/@headlessui-react/src/components/focus-trap/README.md deleted file mode 100644 index 718c223..0000000 --- a/packages/@headlessui-react/src/components/focus-trap/README.md +++ /dev/null @@ -1,64 +0,0 @@ -## FocusTrap - -- [Installation](#installation) -- [Basic example](#basic-example) -- [Component API](#component-api) - -A component for making sure that you can't Tab out of the contents of this -component. - -Focus strategy: - -- An `initialFocus` prop can be passed in, this is a `ref` object, which is a ref to the element that should receive initial focus. -- If an input element exists with an `autoFocus` prop, it will receive initial focus. -- If none of those exists, it will try and focus the first focusable element. -- If that doesn't exist, it will throw an error. - -Once the `FocusTrap` will unmount, the focus will be restored to the element that was focused _before_ the `FocusTrap` was rendered. - -> **NOTE:** This component will throw when there are no focusable elements. -> This is an accessibility feature. At least try to provide a close button or -> similar so that users don't get stuck. - -### Installation - -```sh -# npm -npm install @headlessui/react - -# Yarn -yarn add @headlessui/react -``` - -### Basic example - -```jsx - -
- - - -
- -``` - -### Component API - -#### FocusTrap - -```jsx - -
- - - -
- -``` - -##### Props - -| Prop | Type | Default | Description | -| :------------- | :--------------------- | :---------- | :--------------------------------------------------------- | -| `as` | String \| Component | `div` | The element or component the `FocusTrap` should render as. | -| `initialFocus` | React.MutableRefObject | `undefined` | A ref to an element that should receive focus first. | diff --git a/packages/@headlessui-react/src/components/listbox/README.md b/packages/@headlessui-react/src/components/listbox/README.md deleted file mode 100644 index d212ba3..0000000 --- a/packages/@headlessui-react/src/components/listbox/README.md +++ /dev/null @@ -1,520 +0,0 @@ -## Listbox (Select) - -[View live demo on CodeSandbox](https://codesandbox.io/s/headlessuireact-listbox-example-57eoj?file=/src/App.js) - -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. - -- [Installation](#installation) -- [Basic example](#basic-example) -- [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) -- [Rendering additional content](#rendering-additional-content) -- [Rendering a different element for a component](#rendering-a-different-element-for-a-component) -- [Component API](#component-api) - -### Installation - -```sh -# npm -npm install @headlessui/react - -# Yarn -yarn add @headlessui/react -``` - -### Basic example - -Listboxes are built using the `Listbox`, `Listbox.Button`, `Listbox.Options`, `Listbox.Option` and `Listbox.Label` components. - -The `Listbox.Button` will automatically open/close the `Listbox.Options` when clicked, and when the menu is open, the list of items receives focus and is automatically navigable via the keyboard. - -```jsx -import { useState } from 'react' -import { Listbox } from '@headlessui/react' - -const people = [ - { id: 1, name: 'Durward Reynolds', unavailable: false }, - { id: 2, name: 'Kenton Towne', unavailable: false }, - { id: 3, name: 'Therese Wunsch', unavailable: false }, - { id: 4, name: 'Benedict Kessler', unavailable: true }, - { id: 5, name: 'Katelyn Rohan', unavailable: false }, -] - -function MyListbox() { - const [selectedPerson, setSelectedPerson] = useState(people[0]) - - return ( - - {selectedPerson.name} - - {people.map(person => ( - - {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 [render props](https://reactjs.org/docs/render-props.html) that you can use to apply the styles you'd like to apply yourself. - -To style the active `Listbox.Option` you can read the `active` render prop argument, 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 `Listbox.Option` you can read the `selected` render prop argument, which tells you whether or not that listbox option is the option that is currently the `value` passed to the `Listbox`. - -> Note: An option can be both **active** and **selected** at the same time! - -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, a checkmark is also common. - -```jsx -import { useState, Fragment } from 'react' -import { Listbox } from '@headlessui/react' -import CheckmarkIcon from './CheckmarkIcon' - -const people = [ - { id: 1, name: 'Durward Reynolds' }, - { id: 2, name: 'Kenton Towne' }, - { id: 3, name: 'Therese Wunsch' }, - { id: 4, name: 'Benedict Kessler' }, - { id: 5, name: 'Katelyn Rohan' }, -] - -function MyListbox() { - const [selectedPerson, setSelectedPerson] = useState(people[0]) - - return ( - - {selectedPerson.name} - - {people.map(person => ( - /* Use the `active` state to conditionally style the active option. */ - /* Use the `selected` state to conditionally style the selected option. */ - - {({ active, selected }) => ( -
  • - {selected && } - {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 `Listbox.Label`. - -```jsx -import { useState, Fragment } from 'react' -import { Listbox } from '@headlessui/react' - -const people = [ - { id: 1, name: 'Durward Reynolds' }, - { id: 2, name: 'Kenton Towne' }, - { id: 3, name: 'Therese Wunsch' }, - { id: 4, name: 'Benedict Kessler' }, - { id: 5, name: 'Katelyn Rohan' }, -] - -function MyListbox() { - const [selectedPerson, setSelectedPerson] = useState(people[0]) - - return ( - - Assignee: - {selectedPerson.name} - - {people.map(person => ( - - {person.name} - - ))} - - - ) -} -``` - -### Showing/hiding the listbox - -By default, your `Listbox.Options` instance will be shown/hidden automatically based on the internal `open` state tracked within the `Listbox` component itself. - -```jsx -import { useState } from 'react' -import { Listbox } from '@headlessui/react' - -const people = [ - { id: 1, name: 'Durward Reynolds', unavailable: false }, - { id: 2, name: 'Kenton Towne', unavailable: false }, - { id: 3, name: 'Therese Wunsch', unavailable: false }, - { id: 4, name: 'Benedict Kessler', unavailable: true }, - { id: 5, name: 'Katelyn Rohan', unavailable: false }, -] - -function MyListbox() { - const [selectedPerson, setSelectedPerson] = useState(people[0]) - - return ( - - {selectedPerson.name} - - {/* By default, this will automatically show/hide when the Listbox.Button is pressed. */} - - {people.map(person => ( - - {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 `Listbox.Options` 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. - -```jsx -import { useState } from 'react' -import { Listbox } from '@headlessui/react' - -const people = [ - { id: 1, name: 'Durward Reynolds', unavailable: false }, - { id: 2, name: 'Kenton Towne', unavailable: false }, - { id: 3, name: 'Therese Wunsch', unavailable: false }, - { id: 4, name: 'Benedict Kessler', unavailable: true }, - { id: 5, name: 'Katelyn Rohan', unavailable: false }, -] - -function MyListbox() { - const [selectedPerson, setSelectedPerson] = useState(people[0]) - - return ( - - {({ open }) => ( - <> - {selectedPerson.name} - {open && ( -
    - {/* Using `static`, `Listbox.Options` is always rendered and ignores the `open` state. */} - - {people.map(person => ( - - {person.name} - - ))} - -
    - )} - - )} -     - ) -} -``` - -### Disabling an option - -Use the `disabled` prop to disable a `Listbox.Option`. This will make it unselectable via keyboard navigation, and it will be skipped when pressing the up/down arrows. - -```jsx -import { useState } from 'react' -import { Listbox } from '@headlessui/react' - -const people = [ - { id: 1, name: 'Durward Reynolds', unavailable: false }, - { id: 2, name: 'Kenton Towne', unavailable: false }, - { id: 3, name: 'Therese Wunsch', unavailable: false }, - { id: 4, name: 'Benedict Kessler', unavailable: true }, - { id: 5, name: 'Katelyn Rohan', unavailable: false }, -] - -function MyListbox() { - const [selectedPerson, setSelectedPerson] = useState(people[0]) - - return ( - - {selectedPerson.name} - - {people.map(person => ( - /* Disabled options will be skipped by keyboard navigation. */ - - {person.name} - - ))} - - - ) -} -``` - -### Transitions - -To animate the opening/closing of the listbox panel, use the provided `Transition` component. All you need to do is mark your `Listbox.Options` as `static`, wrap it in a ``, and the transition will be applied automatically. - -```jsx -import { useState } from 'react' -import { Listbox, Transition } from '@headlessui/react' - -const people = [ - { id: 1, name: 'Durward Reynolds', unavailable: false }, - { id: 2, name: 'Kenton Towne', unavailable: false }, - { id: 3, name: 'Therese Wunsch', unavailable: false }, - { id: 4, name: 'Benedict Kessler', unavailable: true }, - { id: 5, name: 'Katelyn Rohan', unavailable: false }, -] - -function MyListbox() { - const [selectedPerson, setSelectedPerson] = useState(people[0]) - - return ( - - {({ open }) => ( - <> - {selectedPerson.name} - {/* Use the Transition + open render prop argument to add transitions. */} - - - {people.map(person => ( - - {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, `Listbox.Label` renders a `label` by default, `Listbox.Button` renders a `button` by default, `Listbox.Options` renders a `ul` and `Listbox.Option` 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. - -```jsx -import { useState } from 'react' -import { Listbox } from '@headlessui/react' - -const people = [ - { id: 1, name: 'Durward Reynolds' }, - { id: 2, name: 'Kenton Towne' }, - { id: 3, name: 'Therese Wunsch' }, - { id: 4, name: 'Benedict Kessler' }, - { id: 5, name: 'Katelyn Rohan' }, -] - -function MyListbox() { - const [selectedPerson, setSelectedPerson] = useState(people[0]) - - return ( - - {selectedPerson.name} - - {people.map(person => ( - - {person.name} - - ))} - - - ) -} -``` - -To tell an element to render its children directly with no wrapper element, use `as={React.Fragment}`. - -```jsx -import { useState, Fragment } from 'react' -import { Listbox } from '@headlessui/react' - -const people = [ - { id: 1, name: 'Durward Reynolds' }, - { id: 2, name: 'Kenton Towne' }, - { id: 3, name: 'Therese Wunsch' }, - { id: 4, name: 'Benedict Kessler' }, - { id: 5, name: 'Katelyn Rohan' }, -] - -function MyListbox() { - const [selectedPerson, setSelectedPerson] = useState(people[0]) - - return ( - - {selectedPerson.name} - - {people.map(person => ( - - {person.name} - - ))} - - - ) -} -``` - -### Component API - -#### Listbox - -```jsx -import { useState } from 'react' -import { Listbox } from '@headlessui/react' - -const people = [ - { id: 1, name: 'Durward Reynolds' }, - { id: 2, name: 'Kenton Towne' }, - { id: 3, name: 'Therese Wunsch' }, - { id: 4, name: 'Benedict Kessler' }, - { id: 5, name: 'Katelyn Rohan' }, -] - -function MyListbox() { - const [selectedPerson, setSelectedPerson] = useState(people[0]) - - return ( - - {selectedPerson.name} - - {people.map(person => ( - - {person.name} - - ))} - - - ) -} -``` - -##### Props - -| Prop | Type | Default | Description | -| :--------- | :------------------ | :-------------------------------------- | :------------------------------------------------------- | -| `as` | String \| Component | `React.Fragment` _(no wrapper element_) | The element or component the `Listbox` should render as. | -| `disabled` | Boolean | `false` | Enable/Disable the `Listbox` component. | -| `value` | `T` | - | The selected value. | -| `onChange` | `(value: T): void` | - | The function to call when a new option is selected. | - -##### Render prop object - -| Prop | Type | Description | -| :--------- | :------ | :-------------------------------------- | -| `open` | Boolean | Whether or not the listbox is open. | -| `disabled` | Boolean | Whether or not the listbox is disabled. | - -#### Listbox.Button - -```jsx - - {({ open }) => ( - <> - More options - - - )} - -``` - -##### Props - -| Prop | Type | Default | Description | -| :--- | :------------------ | :------- | :-------------------------------------------------------------- | -| `as` | String \| Component | `button` | The element or component the `Listbox.Button` should render as. | - -##### Render prop object - -| Prop | Type | Description | -| :--------- | :------ | :-------------------------------------- | -| `open` | Boolean | Whether or not the listbox is open. | -| `disabled` | Boolean | Whether or not the listbox is disabled. | - -#### Listbox.Label - -```jsx -Enable notifications -``` - -##### Props - -| Prop | Type | Default | Description | -| :--- | :------------------ | :------ | :------------------------------------------------------------- | -| `as` | String \| Component | `label` | The element or component the `Listbox.Label` should render as. | - -##### Render prop object - -| Prop | Type | Description | -| :--------- | :------ | :-------------------------------------- | -| `open` | Boolean | Whether or not the listbox is open. | -| `disabled` | Boolean | Whether or not the listbox is disabled. | - -#### Listbox.Options - -```jsx - - {/* ... */}> - {/* ... */}> - -``` - -##### Props - -| Prop | Type | Default | Description | -| :-------- | :------------------ | :------ | :-------------------------------------------------------------------------------- | -| `as` | String \| Component | `ul` | The element or component the `Listbox.Options` 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. | - -> **note**: `static` and `unmount` can not be used at the same time. You will get a TypeScript error if you try to do it. - -##### Render prop object - -| Prop | Type | Description | -| :----- | :------ | :---------------------------------- | -| `open` | Boolean | Whether or not the listbox is open. | - -#### Listbox.Option - -```jsx -Option A -``` - -##### Props - -| Prop | Type | Default | Description | -| :--------- | :------------------ | :------ | :-------------------------------------------------------------------------------------- | -| `as` | String \| Component | `li` | The element or component the `Listbox.Option` 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. | - -##### Render prop object - -| 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. | diff --git a/packages/@headlessui-react/src/components/menu/README.md b/packages/@headlessui-react/src/components/menu/README.md deleted file mode 100644 index a28a032..0000000 --- a/packages/@headlessui-react/src/components/menu/README.md +++ /dev/null @@ -1,406 +0,0 @@ -## Menu Button (Dropdown) - -[View live demo on CodeSandbox](https://codesandbox.io/s/headlessuireact-menu-example-b6xje?file=/src/App.js) - -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. - -- [Installation](#installation) -- [Basic example](#basic-example) -- [Styling the active item](#styling-the-active-item) -- [Showing/hiding the menu](#showinghiding-the-menu) -- [Disabling an item](#disabling-an-item) -- [Transitions](#transitions) -- [Rendering additional content](#rendering-additional-content) -- [Rendering a different element for a component](#rendering-a-different-element-for-a-component) -- [Component API](#component-api) - -### Installation - -```sh -# npm -npm install @headlessui/react - -# Yarn -yarn add @headlessui/react -``` - -### Basic example - -Menu Buttons are built using the `Menu`, `Menu.Button`, `Menu.Items`, and `Menu.Item` components. - -The `Menu.Button` will automatically open/close the `Menu.Items` when clicked, and when the menu is open, the list of items receives focus and is automatically navigable via the keyboard. - -```jsx -import { Menu } from '@headlessui/react' - -function MyDropdown() { - return ( - - More - - - {({ active }) => ( - - Account settings - - )} - - - {({ active }) => ( - - Documentation - - )} - - - Invite a friend (coming soon!) - - - - ) -} -``` - -### Styling the active item - -This is a headless component so there are no styles included by default. Instead, the components expose useful information via [render props](https://reactjs.org/docs/render-props.html) that you can use to apply the styles you'd like to apply yourself. - -To style the active `Menu.Item` you can read the `active` render prop argument, 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. - -```jsx -import { Menu } from '@headlessui/react' - -function MyDropdown() { - return ( - - More - - {/* Use the `active` state to conditionally style the active item. */} - - {({ active }) => ( - - Account settings - - )} - - {/* ... */} - - - ) -} -``` - -### Showing/hiding the menu - -By default, your `Menu.Items` instance will be shown/hidden automatically based on the internal `open` state tracked within the `Menu` component itself. - -```jsx -import { Menu } from '@headlessui/react' - -function MyDropdown() { - return ( - - More - - {/* By default, this will automatically show/hide when the Menu.Button is pressed. */} - - {/* ... */} - {/* ... */} - - - ) -} -``` - -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 `Menu.Items` 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. - -```jsx -import { Menu } from '@headlessui/react' - -function MyDropdown() { - return ( - - {({ open }) => ( - More - {open && ( -
    - {/* Using `static`, `Menu.Items` is always rendered and ignores the `open` state. */} - - {/* ... */} - {/* ... */} - -
    - )} - )} -     - ) -} -``` - -### Disabling an item - -Use the `disabled` prop to disable a `Menu.Item`. This will make it unselectable via keyboard navigation, and it will be skipped when pressing the up/down arrows. - -```jsx -import { Menu } from '@headlessui/react' - -function MyDropdown() { - return ( - - More - - {/* ... */} - - {/* This item will be skipped by keyboard navigation. */} - - Invite a friend (coming soon!) - - - {/* ... */} - - - ) -} -``` - -### Transitions - -To animate the opening/closing of the menu panel, use the provided `Transition` component. All you need to do is mark your `Menu.Items` as `static`, wrap it in a ``, and the transition will be applied automatically. - -```jsx -import { Menu, Transition } from '@headlessui/react' - -function MyDropdown() { - return ( - - {({ open }) => ( - <> - More - - {/* Use the Transition + open render prop argument to add transitions. */} - - - {/* ... */} - {/* ... */} - - - - )} - - ) -} -``` - -### 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. - -```jsx -import { Menu } from '@headlessui/react' - -function MyDropdown() { - return ( - - More - -
    -

    Signed in as

    -

    tom@example.com

    -
    - - {({ active }) => ( - - Account settings - - )} - - - {/* ... */} -     -     - ) -} -``` - -Note that only `Menu.Item` 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, `Menu.Button` renders a `button` by default, and `Menu.Items` renders a `div`. `Menu` and `Menu.Item` 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. - -```jsx -import { Menu } from '@headlessui/react' - -function MyDropdown() { - return ( - {/* Render a `div` instead of no wrapper element */} - - More - {/* Render a `ul` instead of a `div` */} - - {/* Render an `li` instead of no wrapper element */} - - {({ active }) => ( - - Account settings - - )} - - - {/* ... */} - - - ) -} -``` - -To tell an element to render its children directly with no wrapper element, use `as={React.Fragment}`. - -```jsx -import { Menu } from '@headlessui/react' - -function MyDropdown() { - return ( - - {/* Render no wrapper, instead pass in a button manually. */} - - - - - - {({ active }) => ( - - Account settings - - )} - - {/* ... */} - - - ) -} -``` - -### Component API - -#### Menu - -```jsx - - More - - {/* ... */} - {/* ... */} - - -``` - -##### Props - -| Prop | Type | Default | Description | -| :--- | :------------------ | :-------------------------------------- | :---------------------------------------------------- | -| `as` | String \| Component | `React.Fragment` _(no wrapper element_) | The element or component the `Menu` should render as. | - -##### Render prop object - -| Prop | Type | Description | -| :----- | :------ | :------------------------------- | -| `open` | Boolean | Whether or not the menu is open. | - -#### Menu.Button - -```jsx - - {({ open }) => ( - <> - More options - - - )} - -``` - -##### Props - -| Prop | Type | Default | Description | -| :--- | :------------------ | :------- | :----------------------------------------------------------- | -| `as` | String \| Component | `button` | The element or component the `Menu.Button` should render as. | - -##### Render prop object - -| Prop | Type | Description | -| :----- | :------ | :------------------------------- | -| `open` | Boolean | Whether or not the menu is open. | - -#### Menu.Items - -```jsx - - {/* ... */}> - {/* ... */}> - -``` - -##### Props - -| Prop | Type | Default | Description | -| :-------- | :------------------ | :------ | :-------------------------------------------------------------------------------- | -| `as` | String \| Component | `div` | The element or component the `Menu.Items` 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. | - -> **note**: `static` and `unmount` can not be used at the same time. You will get a TypeScript error if you try to do it. - -##### Render prop object - -| Prop | Type | Description | -| :----- | :------ | :------------------------------- | -| `open` | Boolean | Whether or not the menu is open. | - -#### Menu.Item - -```jsx - - {({ active }) => ( - - Account settings - - )} - -``` - -##### Props - -| Prop | Type | Default | Description | -| :--------- | :------------------ | :-------------------------------------- | :------------------------------------------------------------------------------------ | -| `as` | String \| Component | `React.Fragment` _(no wrapper element)_ | The element or component the `Menu.Item` should render as. | -| `disabled` | Boolean | `false` | Whether or not the item should be disabled for keyboard navigation and ARIA purposes. | - -##### Render prop object - -| 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. | diff --git a/packages/@headlessui-react/src/components/popover/README.md b/packages/@headlessui-react/src/components/popover/README.md deleted file mode 100644 index 90e8f89..0000000 --- a/packages/@headlessui-react/src/components/popover/README.md +++ /dev/null @@ -1,164 +0,0 @@ -## Popover - -- [Installation](#installation) -- [Basic example](#basic-example) -- [Component API](#component-api) - -This component can be used for navigation menu's, mobile menu's and flyout menu's. - -### Installation - -```sh -# npm -npm install @headlessui/react - -# Yarn -yarn add @headlessui/react -``` - -### Basic example - -```jsx - - - Solutions - - Analytics - Engagement - Security - Integrations - Automations - - - - Pricing - Docs - - - More - - Help Center - Guides - Events - Security - - - -``` - -### Component API - -#### Popover - -```jsx - - - Solutions - - Analytics - Engagement - Security - Integrations - Automations - - - - Pricing - Docs - - - More - - Help Center - Guides - Events - Security - - - -``` - -##### Props - -| Prop | Type | Default | Description | -| :--- | :------------------ | :------ | :------------------------------------------------------- | -| `as` | String \| Component | `div` | The element or component the `Popover` should render as. | - -##### Render prop object - -| Prop | Type | Description | -| :----- | :------ | :--------------------------------- | -| `open` | Boolean | Whether or not the dialog is open. | - -#### Popover.Overlay - -This can be used to create an overlay for your Popover component. Clicking on the overlay will close the Popover. - -##### Props - -| Prop | Type | Default | Description | -| :--- | :------------------ | :------ | :--------------------------------------------------------------- | -| `as` | String \| Component | `div` | The element or component the `Popover.Overlay` should render as. | - -##### Render prop object - -| Prop | Type | Description | -| :----- | :------ | :------------------------------------- | -| `open` | Boolean | Whether or not the disclosure is open. | - -#### Popover.Button - -This is the trigger component to open a Popover. You can also use this -`Popover.Button` component inside a `Popover.Panel`, if you do so, then it will -behave as a `close` button. We will also make sure to provide the correct -`aria-*` attributes onto the button. - -##### Props - -| Prop | Type | Default | Description | -| :--- | :------------------ | :------- | :-------------------------------------------------------------- | -| `as` | String \| Component | `button` | The element or component the `Popover.Button` should render as. | - -##### Render prop object - -| Prop | Type | Description | -| :----- | :------ | :------------------------------------- | -| `open` | Boolean | Whether or not the disclosure is open. | - -#### Popover.Panel - -This component contains the contents of your Popover. - -##### Props - -| Prop | Type | Default | Description | -| :-------- | :------------------ | :------ | :------------------------------------------------------------------------------------------------------------------------------------------ | -| `as` | String \| Component | `div` | The element or component the `Popover.Panel` should render as. | -| `focus` | Boolean | `false` | This will force focus inside the `Popover.Panel` when the `Popover` is open. It will also close the `Popover` if focus left this component. | -| `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. | - -> **note**: `static` and `unmount` can not be used at the same time. You will get a TypeScript error if you try to do it. - -##### Render prop object - -| Prop | Type | Description | -| :----- | :------ | :------------------------------------- | -| `open` | Boolean | Whether or not the disclosure is open. | - -#### Popover.Group - -This allows you to wrap multiple elements and Popover's inside a group. - -- When you tab out of a `Popover.Panel`, it will focus the next `Popover.Button` in line. -- If focus left the `Popover.Group` it will close all the `Popover`'s. - -##### Props - -| Prop | Type | Default | Description | -| :--- | :------------------ | :------ | :------------------------------------------------------------- | -| `as` | String \| Component | `div` | The element or component the `Popover.Group` should render as. | - -##### Render prop object - -- None diff --git a/packages/@headlessui-react/src/components/portal/README.md b/packages/@headlessui-react/src/components/portal/README.md deleted file mode 100644 index 12f7af2..0000000 --- a/packages/@headlessui-react/src/components/portal/README.md +++ /dev/null @@ -1,45 +0,0 @@ -## Portal - -- [Installation](#installation) -- [Basic example](#basic-example) -- [Component API](#component-api) - -A component for rendering your contents within a Portal (at the end of `document.body`). - -### Installation - -```sh -# npm -npm install @headlessui/react - -# Yarn -yarn add @headlessui/react -``` - -### Basic example - -```jsx - -

    This will be rendered inside a Portal, at the end of `document.body`

    -     -``` - -### Component API - -#### Portal - -```jsx - -

    This will be rendered inside a Portal, at the end of `document.body`

    -     -``` - -##### Props - -| Prop | Type | Default | Description | -| :--- | :------------------ | :-------------------------------------- | :------------------------------------------------------ | -| `as` | String \| Component | `React.Fragment` _(no wrapper element_) | The element or component the `Portal` should render as. | - -##### Render prop object - -- None diff --git a/packages/@headlessui-react/src/components/radio-group/README.md b/packages/@headlessui-react/src/components/radio-group/README.md deleted file mode 100644 index f9dee11..0000000 --- a/packages/@headlessui-react/src/components/radio-group/README.md +++ /dev/null @@ -1,89 +0,0 @@ -## RadioGroup - -A component for grouping radio options. - -- [Installation](#installation) -- [Basic example](#basic-example) -- [Component API](#component-api) - -### Installation - -```sh -# npm -npm install @headlessui/react - -# Yarn -yarn add @headlessui/react -``` - -### Basic example - -```jsx -import React, { useState } from 'react' -import { RadioGroup } from '@headlessui/react' - -function Example() { - let [deliveryMethod, setDeliveryMethod] = useState(undefined) - - return ( - - Pizza Delivery - Pickup - Home delivery - Dine in - - ) -} -``` - -### Component API - -#### RadioGroup - -```jsx -let [deliveryMethod, setDeliveryMethod] = useState(undefined) - - - Pickup - Home delivery - Dine in - -``` - -##### Props - -| Prop | Type | Default | Description | -| :--------- | :------------------ | :---------- | :---------------------------------------------------------- | -| `as` | String \| Component | `div` | The element or component the `RadioGroup` should render as. | -| `value` | `T` \| undefined | `undefined` | The current selected value in the `RadioGroup`. | -| `onChange` | Function | `undefined` | The function called to update the `RadioGroup` value. | - -##### Render prop object - -- None - -#### RadioGroup.Option - -```jsx -let [deliveryMethod, setDeliveryMethod] = useState(undefined) - - - Pickup - Home delivery - Dine in - -``` - -##### Props - -| Prop | Type | Default | Description | -| :------ | :------------------ | :---------- | :------------------------------------------------------------------------------------------------------------------------- | -| `as` | String \| Component | `div` | The element or component the `RadioGroup` should render as. | -| `value` | `T` \| undefined | `undefined` | The value of the current `RadioGroup.Option`. The type should match the type of the `value` in the `RadioGroup` component. | - -##### Render prop object - -| Prop | Type | Description | -| :-------- | :------ | :----------------------------------------------------------------- | -| `active` | Boolean | Whether or not the option is active (using the mouse or keyboard). | -| `checked` | Boolean | Whether or not the current option is the checked value. | diff --git a/packages/@headlessui-react/src/components/switch/README.md b/packages/@headlessui-react/src/components/switch/README.md deleted file mode 100644 index bb35a24..0000000 --- a/packages/@headlessui-react/src/components/switch/README.md +++ /dev/null @@ -1,161 +0,0 @@ -## Switch (Toggle) - -[View live demo on CodeSandbox](https://codesandbox.io/s/headlessuireact-switch-example-y40i1?file=/src/App.js) - -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. - -- [Installation](#installation) -- [Basic example](#basic-example) -- [Using a custom label](#using-a-custom-label) -- [Component API](#component-api) - -### Installation - -```sh -# npm -npm install @headlessui/react - -# Yarn -yarn add @headlessui/react -``` - -### Basic example - -Switches are built using the `Switch` component. Optionally you can also use the `Switch.Group` and `Switch.Label` components. - -```jsx -import { useState } from 'react' -import { Switch } from '@headlessui/react' - -function NotificationsToggle() { - const [enabled, setEnabled] = useState(false) - - return ( - - Enable notifications - - - ) -} -``` - -### 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 `Switch.Label` outside of the `Switch`, as long as both the switch and label are within a parent `Switch.Group`. - -Clicking the label will toggle the switch state, like you'd expect from a native checkbox. - -```jsx -import { useState } from 'react' -import { Switch } from '@headlessui/react' - -function NotificationsToggle() { - const [enabled, setEnabled] = useState(false) - - return ( - - Enable notifications - - - - - ) -} -``` - -### Component API - -#### Switch - -```jsx - - Enable notifications - {/* ... */} - -``` - -##### Props - -| Prop | Type | Default | Description | -| :--------- | :----------------------- | :------- | :------------------------------------------------------ | -| `as` | String \| Component | `button` | The element or component the `Switch` should render as. | -| `checked` | Boolean | - | Whether or not the switch is checked. | -| `onChange` | `(value: boolean): void` | - | The function to call when the switch is toggled. | - -##### Render prop object - -| Prop | Type | Description | -| :-------- | :------ | :------------------------------------ | -| `checked` | Boolean | Whether or not the switch is checked. | - -#### Switch.Label - -```jsx - - Enable notifications - - {/* ... */} - - -``` - -##### Props - -| Prop | Type | Default | Description | -| :-------- | :------------------ | :------ | :----------------------------------------------------------------------------------- | -| `as` | String \| Component | `label` | The element or component the `Switch.Label` should render as. | -| `passive` | Boolean | `false` | When `passive` is `false`, clicking the `Switch.Label` will not toggle the `Switch`. | - -#### Switch.Description - -```jsx - - Enable notifications - - {/* ... */} - - -``` - -##### Props - -| Prop | Type | Default | Description | -| :--- | :------------------ | :------ | :------------------------------------------------------------------ | -| `as` | String \| Component | `label` | The element or component the `Switch.Description` should render as. | - -#### Switch.Group - -```jsx - - Enable notifications - - {/* ... */} - - -``` - -##### Props - -| Prop | Type | Default | Description | -| :--- | :------------------ | :-------------------------------------- | :------------------------------------------------------------ | -| `as` | String \| Component | `React.Fragment` _(no wrapper element)_ | The element or component the `Switch.Group` should render as. | diff --git a/packages/@headlessui-react/src/components/transitions/README.md b/packages/@headlessui-react/src/components/transitions/README.md deleted file mode 100644 index 16e3213..0000000 --- a/packages/@headlessui-react/src/components/transitions/README.md +++ /dev/null @@ -1,308 +0,0 @@ -## Transition - -[View live demo on CodeSandbox](https://codesandbox.io/s/headlessuireact-menu-example-b6xje?file=/src/App.js) - -The `Transition` component lets you add enter/leave transitions to conditionally rendered elements, using CSS classes to control the actual transition styles in the different stages of the transition. - -- [Installation](#installation) -- [Basic example](#basic-example) -- [Showing and hiding content](#showing-and-hiding-content) -- [Animating transitions](#animating-transitions) -- [Co-ordinating multiple transitions](#co-ordinating-multiple-transitions) -- [Transitioning on initial mount](#transitioning-on-initial-mount) -- [Component API](#component-api) - -### Installation - -```sh -# npm -npm install @headlessui/react - -# Yarn -yarn add @headlessui/react -``` - -### Basic example - -The `Transition` accepts a `show` prop that controls whether the children should be shown or hidden, and a set of lifecycle props (like `enterFrom`, and `leaveTo`) that let you add CSS classes at specific phases of a transition. - -```tsx -import { Transition } from '@headlessui/react' -import { useState } from 'react' - -function MyComponent() { - const [isOpen, setIsOpen] = useState(false) - - return ( - <> - - - I will fade in and out - - - ) -} -``` - -### Showing and hiding content - -Wrap the content that should be conditionally rendered in a `` component, and use the `show` prop to control whether the content should be visible or hidden. - -```tsx -import { Transition } from '@headlessui/react' -import { useState } from 'react' - -function MyComponent() { - const [isOpen, setIsOpen] = useState(false) - - return ( - <> - - - I will fade in and out - - - ) -} -``` - -The `Transition` component will render a `div` by default, but you can use the `as` prop to render a different element instead if needed. Any other HTML attributes (like `className`) can be added directly to the `Transition` the same way they would be to regular elements. - -```tsx -import { Transition } from '@headlessui/react' -import { useState } from 'react' - -function MyComponent() { - const [isOpen, setIsOpen] = useState(false) - - return ( - <> - - - I will fade in and out - - - ) -} -``` - -### Animating transitions - -By default, a `Transition` will enter and leave instantly, which is probably not what you're looking for if you're using this library. - -To animate your enter/leave transitions, add classes that provide the styling for each phase of the transitions using these props: - -- **enter**: Applied the entire time an element is entering. Usually you define your duration and what properties you want to transition here, for example `transition-opacity duration-75`. -- **enterFrom**: The starting point to enter from, for example `opacity-0` if something should fade in. -- **enterTo**: The ending point to enter to, for example `opacity-100` after fading in. -- **leave**: Applied the entire time an element is leaving. Usually you define your duration and what properties you want to transition here, for example `transition-opacity duration-75`. -- **leaveFrom**: The starting point to leave from, for example `opacity-100` if something should fade out. -- **leaveTo**: The ending point to leave to, for example `opacity-0` after fading out. - -Here's an example: - -```tsx -import { Transition } from '@headlessui/react' -import { useState } from 'react' - -function MyComponent() { - const [isOpen, setIsOpen] = useState(false) - - return ( - <> - - - I will fade in and out - - - ) -} -``` - -In this example, the transitioning element will take 75ms to enter (that's the `duration-75` class), and will transition the opacity property during that time (that's `transition-opacity`). - -It will start completely transparent before entering (that's `opacity-0` in the `enterFrom` phase), and fade in to completely opaque (`opacity-100`) when finished (that's the `enterTo` phase). - -When the element is being removed (the `leave` phase), it will transition the opacity property, and spend 150ms doing it (`transition-opacity duration-150`). - -It will start as completely opaque (the `opacity-100` in the `leaveFrom` phase), and finish as completely transparent (the `opacity-0` in the `leaveTo` phase). - -All of these props are optional, and will default to just an empty string. - -### Co-ordinating multiple transitions - -Sometimes you need to transition multiple elements with different animations but all based on the same state. For example, say the user clicks a button to open a sidebar that slides over the screen, and you also need to fade-in a background overlay at the same time. - -You can do this by wrapping the related elements with a parent `Transition` component, and wrapping each child that needs its own transition styles with a `Transition.Child` component, which will automatically communicate with the parent `Transition` and inherit the parent's `show` state. - -```tsx -import { Transition } from '@headlessui/react' - -function Sidebar({ isOpen }) { - return ( - - {/* Background overlay */} - - {/* ... */} - - - {/* Sliding sidebar */} - - {/* ... */} - - - ) -} -``` - -The `Transition.Child` component has the exact same API as the `Transition` component, but with no `show` prop, since the `show` value is controlled by the parent. - -Parent `Transition` components will always automatically wait for all children to finish transitioning before unmounting, so you don't need to manage any of that timing yourself. - -### Transitioning on initial mount - -If you want an element to transition the very first time it's rendered, set the `appear` prop to `true`. - -This is useful if you want something to transition in on initial page load, or when its parent is conditionally rendered. - -```tsx -import { Transition } from '@headlessui/react' - -function MyComponent({ isShowing }) { - return ( - - {/* Your content goes here*/} - - ) -} -``` - -### Component API - -#### Transition - -```jsx - - {/* Your content goes here*/} - -``` - -##### Props - -| Prop | Type | Default | Description | -| :------------ | :------------------ | :------ | :------------------------------------------------------------------------------------ | -| `show` | Boolean | - | Whether the children should be shown or hidden. | -| `as` | String \| Component | `div` | The element or component to render in place of the `Transition` itself. | -| `appear` | Boolean | `false` | Whether the transition should run on initial mount. | -| `unmount` | Boolean | `true` | Whether the element should be `unmounted` or `hidden` based on the show state. | -| `enter` | String | `''` | Classes to add to the transitioning element during the entire enter phase. | -| `enterFrom` | String | `''` | Classes to add to the transitioning element before the enter phase starts. | -| `enterTo` | String | `''` | Classes to add to the transitioning element immediately after the enter phase starts. | -| `leave` | String | `''` | Classes to add to the transitioning element during the entire leave phase. | -| `leaveFrom` | String | `''` | Classes to add to the transitioning element before the leave phase starts. | -| `leaveTo` | String | `''` | Classes to add to the transitioning element immediately after the leave phase starts. | -| `beforeEnter` | Function | - | Callback which is called before we start the enter transition. | -| `afterEnter` | Function | - | Callback which is called after we finished the enter transition. | -| `beforeLeave` | Function | - | Callback which is called before we start the leave transition. | -| `afterLeave` | Function | - | Callback which is called after we finished the leave transition. | - -##### Render prop object - -- None - -#### Transition.Child - -```jsx - - - {/* ... */} - - {/* ... */} - -``` - -##### Props - -| Prop | Type | Default | Description | -| :------------ | :------------------ | :------ | :------------------------------------------------------------------------------------ | -| `as` | String \| Component | `div` | The element or component to render in place of the `Transition.Child` itself. | -| `appear` | Boolean | `false` | Whether the transition should run on initial mount. | -| `unmount` | Boolean | `true` | Whether the element should be `unmounted` or `hidden` based on the show state. | -| `enter` | String | `''` | Classes to add to the transitioning element during the entire enter phase. | -| `enterFrom` | String | `''` | Classes to add to the transitioning element before the enter phase starts. | -| `enterTo` | String | `''` | Classes to add to the transitioning element immediately after the enter phase starts. | -| `leave` | String | `''` | Classes to add to the transitioning element during the entire leave phase. | -| `leaveFrom` | String | `''` | Classes to add to the transitioning element before the leave phase starts. | -| `leaveTo` | String | `''` | Classes to add to the transitioning element immediately after the leave phase starts. | -| `beforeEnter` | Function | - | Callback which is called before we start the enter transition. | -| `afterEnter` | Function | - | Callback which is called after we finished the enter transition. | -| `beforeLeave` | Function | - | Callback which is called before we start the leave transition. | -| `afterLeave` | Function | - | Callback which is called after we finished the leave transition. | - -##### Render prop object - -- None diff --git a/packages/@headlessui-react/src/components/transitions/transition.test.tsx b/packages/@headlessui-react/src/components/transitions/transition.test.tsx index 0439dae..3a3aeb0 100644 --- a/packages/@headlessui-react/src/components/transitions/transition.test.tsx +++ b/packages/@headlessui-react/src/components/transitions/transition.test.tsx @@ -1205,11 +1205,11 @@ describe('Events', () => { let enterHookDiff = eventHandler.mock.calls[1][1] - eventHandler.mock.calls[0][1] expect(enterHookDiff).toBeGreaterThanOrEqual(enterDuration) - expect(enterHookDiff).toBeLessThanOrEqual(enterDuration * 2) + expect(enterHookDiff).toBeLessThanOrEqual(enterDuration * 3) let leaveHookDiff = eventHandler.mock.calls[3][1] - eventHandler.mock.calls[2][1] expect(leaveHookDiff).toBeGreaterThanOrEqual(leaveDuration) - expect(leaveHookDiff).toBeLessThanOrEqual(leaveDuration * 2) + expect(leaveHookDiff).toBeLessThanOrEqual(leaveDuration * 3) }) ) }) diff --git a/packages/@headlessui-vue/README.md b/packages/@headlessui-vue/README.md index de5853e..2df8eb3 100644 --- a/packages/@headlessui-vue/README.md +++ b/packages/@headlessui-vue/README.md @@ -10,7 +10,7 @@

    Total Downloads Latest Release - License + License

    ## Installation @@ -25,30 +25,16 @@ npm install @headlessui/vue yarn add @headlessui/vue ``` -## Components +## Documentation -_This project is still in early development. New components will be added regularly over the coming months._ +For full documentation, visit [headlessui.dev](https://headlessui.dev/vue). -- [Menu Button (Dropdown)](./src/components/menu/README.md) -- [Listbox (Select)](./src/components/listbox/README.md) -- [Switch (Toggle)](./src/components/switch/README.md) -- [Disclosure](./src/components/disclosure/README.md) -- [FocusTrap](./src/components/focus-trap/README.md) -- [Portal](./src/components/portal/README.md) -- [Dialog](./src/components/dialog/README.md) -- [Popover](./src/components/popover/README.md) -- [Radio Group](./src/components/radio-group/README.md) -- [Transition](./src/components/transitions/README.md) +## Community -### Roadmap +For help, discussion about best practices, or any other conversation that would benefit from being searchable: -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). +[Discuss Headless UI on GitHub](https://github.com/tailwindlabs/tailwindcss/discussions) -This includes things like: +For casual chit-chat with others using the library: -- Tabs -- 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. +[Join the Tailwind CSS Discord Server](https://discord.gg/7NF8GNe) diff --git a/packages/@headlessui-vue/src/components/dialog/README.md b/packages/@headlessui-vue/src/components/dialog/README.md deleted file mode 100644 index f27840a..0000000 --- a/packages/@headlessui-vue/src/components/dialog/README.md +++ /dev/null @@ -1,184 +0,0 @@ -## Dialog - -- [Installation](#installation) -- [Basic example](#basic-example) -- [Component API](#component-api) - -This component can be used to render content inside a Dialog/Modal. This contains a ton of features: - -1. Renders inside a `Portal` -2. Controlled component -3. Uses `FocusTrap` with its features (Focus first focusable element, `autoFocus` or `initialFocus` ref) - > **NOTE:** This component will throw when there are no focusable elements. - > This is an accessibility feature. At least try to provide a close button or - > similar so that users don't get stuck. -4. Adds a scroll lock -5. Prevents content jumps by faking your scrollbar width -6. Marks other elements as `inert` (hides other elements from screen readers) -7. Closes on `escape` -8. Closes on click outside -9. Once the Dialog becomes hidden (e.g.: `md:hidden`) it will also emit the `close` event - -### Installation - -```sh -# npm -npm install @headlessui/vue - -# Yarn -yarn add @headlessui/vue -``` - -### Basic example - -```vue - - - -``` - -### Component API - -#### Dialog - -```vue - - - -``` - -##### Props - -| Prop | Type | Default | Description | -| :------------- | :------------------ | :------ | :-------------------------------------------------------------------------------- | -| `open` | Boolean | / | Wether the `Dialog` is open or not. | -| `initialFocus` | HTMLElement | / | A ref to an element that should receive focus first. | -| `as` | String \| Component | `div` | The element or component the `Dialog` 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. | - -> **note**: `static` and `unmount` can not be used at the same time. You will get a TypeScript error if you try to do it. - -##### Events - -| Event Name | Description | -| :--------- | :----------------------------------------------------------------------------------------------------------------------------------- | -| `@close` | Called when the `Dialog` should close. For convenience we emit `false` as the event value so that you can use: `@close="setIsOpen"`. | - -##### Render prop object - -| Prop | Type | Description | -| :----- | :------ | :--------------------------------- | -| `open` | Boolean | Whether or not the dialog is open. | - -#### DialogOverlay - -This can be used to create an overlay for your Dialog component. Clicking on the overlay will close the Dialog. - -##### Props - -| Prop | Type | Default | Description | -| :--- | :------------------ | :------ | :------------------------------------------------------------- | -| `as` | String \| Component | `div` | The element or component the `DialogOverlay` should render as. | - -##### Render prop object - -| Prop | Type | Description | -| :----- | :------ | :--------------------------------- | -| `open` | Boolean | Whether or not the dialog is open. | - -#### DialogTitle - -This is the title for your Dialog. When this is used, it will set the `aria-labelledby` on the Dialog. - -##### Props - -| Prop | Type | Default | Description | -| :--- | :------------------ | :------ | :----------------------------------------------------------- | -| `as` | String \| Component | `h2` | The element or component the `DialogTitle` should render as. | - -##### Render prop object - -| Prop | Type | Description | -| :----- | :------ | :--------------------------------- | -| `open` | Boolean | Whether or not the dialog is open. | - -#### DialogDescription - -This is the description for your Dialog. When this is used, it will set the `aria-describedby` on the Dialog. - -##### Props - -| Prop | Type | Default | Description | -| :--- | :------------------ | :------ | :----------------------------------------------------------------- | -| `as` | String \| Component | `p` | The element or component the `DialogDescription` should render as. | - -##### Render prop object - -| Prop | Type | Description | -| :----- | :------ | :--------------------------------- | -| `open` | Boolean | Whether or not the dialog is open. | diff --git a/packages/@headlessui-vue/src/components/disclosure/README.md b/packages/@headlessui-vue/src/components/disclosure/README.md deleted file mode 100644 index 184a7c2..0000000 --- a/packages/@headlessui-vue/src/components/disclosure/README.md +++ /dev/null @@ -1,81 +0,0 @@ -## Disclosure - -A component for showing/hiding content. - -- [Installation](#installation) -- [Basic example](#basic-example) -- [Component API](#component-api) - -### Installation - -```sh -# npm -npm install @headlessui/vue - -# Yarn -yarn add @headlessui/vue -``` - -### Basic example - -```jsx - - Toggle - Contents - -``` - -### Component API - -#### Disclosure - -```jsx - - Toggle - Contents - -``` - -##### Props - -| Prop | Type | Default | Description | -| :--- | :------------------ | :-------------------------------------- | :---------------------------------------------------------- | -| `as` | String \| Component | `React.Fragment` _(no wrapper element_) | The element or component the `Disclosure` should render as. | - -##### Render prop object - -| Prop | Type | Description | -| :----- | :------ | :------------------------------------- | -| `open` | Boolean | Whether or not the disclosure is open. | - -#### DisclosureButton - -##### Props - -| Prop | Type | Default | Description | -| :--- | :------------------ | :------- | :----------------------------------------------------------------- | -| `as` | String \| Component | `button` | The element or component the `DisclosureButton` should render as. | - -##### Render prop object - -| Prop | Type | Description | -| :----- | :------ | :------------------------------------- | -| `open` | Boolean | Whether or not the disclosure is open. | - -#### DisclosurePanel - -##### Props - -| Prop | Type | Default | Description | -| :-------- | :------------------ | :------ | :-------------------------------------------------------------------------------- | -| `as` | String \| Component | `div` | The element or component the `DisclosurePanel` 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. | - -> **note**: `static` and `unmount` can not be used at the same time. You will get a TypeScript error if you try to do it. - -##### Render prop object - -| Prop | Type | Description | -| :----- | :------ | :------------------------------------- | -| `open` | Boolean | Whether or not the disclosure is open. | diff --git a/packages/@headlessui-vue/src/components/focus-trap/README.md b/packages/@headlessui-vue/src/components/focus-trap/README.md deleted file mode 100644 index ec29174..0000000 --- a/packages/@headlessui-vue/src/components/focus-trap/README.md +++ /dev/null @@ -1,64 +0,0 @@ -## FocusTrap - -- [Installation](#installation) -- [Basic example](#basic-example) -- [Component API](#component-api) - -A component for making sure that you can't Tab out of the contents of this -component. - -Focus strategy: - -- An `initialFocus` prop can be passed in, this is a `ref` object, which is a ref to the element that should receive initial focus. -- If an input element exists with an `autoFocus` prop, it will receive initial focus. -- If none of those exists, it will try and focus the first focusable element. -- If that doesn't exist, it will throw an error. - -Once the `FocusTrap` will unmount, the focus will be restored to the element that was focused _before_ the `FocusTrap` was rendered. - -> **NOTE:** This component will throw when there are no focusable elements. -> This is an accessibility feature. At least try to provide a close button or -> similar so that users don't get stuck. - -### Installation - -```sh -# npm -npm install @headlessui/vue - -# Yarn -yarn add @headlessui/vue -``` - -### Basic example - -```jsx - -
    - - - -
    -     -``` - -### Component API - -#### FocusTrap - -```jsx - -
    - - - -
    -     -``` - -##### Props - -| Prop | Type | Default | Description | -| :------------- | :--------------------- | :---------- | :--------------------------------------------------------- | -| `as` | String \| Component | `div` | The element or component the `FocusTrap` should render as. | -| `initialFocus` | React.MutableRefObject | `undefined` | A ref to an element that should receive focus first. | diff --git a/packages/@headlessui-vue/src/components/listbox/README.md b/packages/@headlessui-vue/src/components/listbox/README.md deleted file mode 100644 index 9173914..0000000 --- a/packages/@headlessui-vue/src/components/listbox/README.md +++ /dev/null @@ -1,712 +0,0 @@ -## Listbox (Select) - -[View live demo on CodeSandbox](https://codesandbox.io/s/headlessuivue-listbox-example-forked-070j0?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. - -- [Installation](#installation) -- [Basic example](#basic-example) -- [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) -- [Rendering additional content](#rendering-additional-content) -- [Rendering a different element for a component](#rendering-a-different-element-for-a-component) -- [Component API](#component-api) - -## Installation - -Please note that **this library only supports Vue 3**. - -```sh -# npm -npm install @headlessui/vue - -# Yarn -yarn add @headlessui/vue -``` - -### 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 - - - -``` - -### 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 - - - -``` - -### 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 - - - -``` - -### 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 - - - -``` - -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 - - - -``` - -### 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 - - - -``` - -### 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 - - - -``` - -### 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 - - - -``` - -To tell an element to render its children directly with no wrapper element, use `as="template"`. - -```vue - - - -``` - -### Component API - -#### Listbox - -```vue - - - -``` - -##### 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. | -| `disabled` | Boolean | `false` | Enable/Disable the `Listbox` component. | - -##### Slot props - -| Prop | Type | Description | -| :--------- | :------ | :-------------------------------------- | -| `open` | Boolean | Whether or not the listbox is open. | -| `disabled` | Boolean | Whether or not the listbox is disabled. | - -#### 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. | -| `disabled` | Boolean | Whether or not the listbox is disabled. | - -#### ListboxLabel - -```vue -Enable notifications -``` - -##### Props - -| Prop | Type | Default | Description | -| :--- | :------------------ | :------ | :------------------------------------------------------------ | -| `as` | String \| Component | `label` | The element or component the `ListboxLabel` should render as. | - -##### Slot props - -| Prop | Type | Description | -| :--------- | :------ | :-------------------------------------- | -| `open` | Boolean | Whether or not the listbox is open. | -| `disabled` | Boolean | Whether or not the listbox is disabled. | - -#### 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. | diff --git a/packages/@headlessui-vue/src/components/menu/README.md b/packages/@headlessui-vue/src/components/menu/README.md deleted file mode 100644 index 9deae99..0000000 --- a/packages/@headlessui-vue/src/components/menu/README.md +++ /dev/null @@ -1,335 +0,0 @@ -## Menu Button (Dropdown) - -[View live demo on CodeSandbox](https://codesandbox.io/s/headlessuivue-menu-example-forked-24f9d?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. - -- [Installation](#installation) -- [Basic example](#basic-example) -- [Styling](#styling) -- [Transitions](#transitions) -- [Component API](#component-api) - -## Installation - -Please note that **this library only supports Vue 3**. - -```sh -# npm -npm install @headlessui/vue - -# Yarn -yarn add @headlessui/vue -``` - -### 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 - - More options - - - - - -``` - -##### 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 - - - Settings - - -``` - -##### 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. | diff --git a/packages/@headlessui-vue/src/components/popover/README.md b/packages/@headlessui-vue/src/components/popover/README.md deleted file mode 100644 index 0ec751e..0000000 --- a/packages/@headlessui-vue/src/components/popover/README.md +++ /dev/null @@ -1,164 +0,0 @@ -## Popover - -- [Installation](#installation) -- [Basic example](#basic-example) -- [Component API](#component-api) - -This component can be used for navigation menu's, mobile menu's and flyout menu's. - -### Installation - -```sh -# npm -npm install @headlessui/vue - -# Yarn -yarn add @headlessui/vue -``` - -### Basic example - -```jsx - - - Solutions - - Analytics - Engagement - Security - Integrations - Automations - - - - Pricing - Docs - - - More - - Help Center - Guides - Events - Security - - - -``` - -### Component API - -#### Popover - -```jsx - - - Solutions - - Analytics - Engagement - Security - Integrations - Automations - - - - Pricing - Docs - - - More - - Help Center - Guides - Events - Security - - - -``` - -##### Props - -| Prop | Type | Default | Description | -| :--- | :------------------ | :------ | :------------------------------------------------------- | -| `as` | String \| Component | `div` | The element or component the `Popover` should render as. | - -##### Render prop object - -| Prop | Type | Description | -| :----- | :------ | :--------------------------------- | -| `open` | Boolean | Whether or not the dialog is open. | - -#### PopoverOverlay - -This can be used to create an overlay for your Popover component. Clicking on the overlay will close the Popover - -##### Props - -| Prop | Type | Default | Description | -| :--- | :------------------ | :------ | :--------------------------------------------------------------- | -| `as` | String \| Component | `div` | The element or component the `PopoverOverlay` should render as. | - -##### Render prop object - -| Prop | Type | Description | -| :----- | :------ | :------------------------------------- | -| `open` | Boolean | Whether or not the disclosure is open. | - -#### PopoverButton - -This is the trigger component to open a Popover You can also use this -`PopoverButton` component inside a `PopoverPanel`, if you do so, then it will -behave as a `close` button. We will also make sure to provide the correct -`aria-*` attributes onto the button. - -##### Props - -| Prop | Type | Default | Description | -| :--- | :------------------ | :------- | :-------------------------------------------------------------- | -| `as` | String \| Component | `button` | The element or component the `PopoverButton` should render as. | - -##### Render prop object - -| Prop | Type | Description | -| :----- | :------ | :------------------------------------- | -| `open` | Boolean | Whether or not the disclosure is open. | - -#### PopoverPanel - -This component contains the contents of your Popover - -##### Props - -| Prop | Type | Default | Description | -| :-------- | :------------------ | :------ | :------------------------------------------------------------------------------------------------------------------------------------------ | -| `as` | String \| Component | `div` | The element or component the `PopoverPanel` should render as. | -| `focus` | Boolean | `false` | This will force focus inside the `PopoverPanel` when the `Popover` is open. It will also close the `Popover` if focus left this component. | -| `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. | - -> **note**: `static` and `unmount` can not be used at the same time. You will get a TypeScript error if you try to do it. - -##### Render prop object - -| Prop | Type | Description | -| :----- | :------ | :------------------------------------- | -| `open` | Boolean | Whether or not the disclosure is open. | - -#### PopoverGroup - -This allows you to wrap multiple elements and Popover's inside a group. - -- When you tab out of a `PopoverPanel`, it will focus the next `PopoverButton` in line. -- If focus left the `PopoverGroup` it will close all the `Popover`'s. - -##### Props - -| Prop | Type | Default | Description | -| :--- | :------------------ | :------ | :------------------------------------------------------------- | -| `as` | String \| Component | `div` | The element or component the `PopoverGroup` should render as. | - -##### Render prop object - -- None diff --git a/packages/@headlessui-vue/src/components/portal/README.md b/packages/@headlessui-vue/src/components/portal/README.md deleted file mode 100644 index 303c9d2..0000000 --- a/packages/@headlessui-vue/src/components/portal/README.md +++ /dev/null @@ -1,45 +0,0 @@ -## Portal - -- [Installation](#installation) -- [Basic example](#basic-example) -- [Component API](#component-api) - -A component for rendering your contents within a Portal (at the end of `document.body`). - -### Installation - -```sh -# npm -npm install @headlessui/vue - -# Yarn -yarn add @headlessui/vue -``` - -### Basic example - -```jsx - -

    This will be rendered inside a Portal, at the end of `document.body`

    -     -``` - -### Component API - -#### Portal - -```jsx - -

    This will be rendered inside a Portal, at the end of `document.body`

    -     -``` - -##### Props - -| Prop | Type | Default | Description | -| :--- | :------------------ | :-------------------------------- | :------------------------------------------------------ | -| `as` | String \| Component | `template` _(no wrapper element_) | The element or component the `Portal` should render as. | - -##### Render prop object - -- None diff --git a/packages/@headlessui-vue/src/components/radio-group/README.md b/packages/@headlessui-vue/src/components/radio-group/README.md deleted file mode 100644 index 4b77bfd..0000000 --- a/packages/@headlessui-vue/src/components/radio-group/README.md +++ /dev/null @@ -1,91 +0,0 @@ -## RadioGroup - -A component for grouping radio options. - -- [Installation](#installation) -- [Basic example](#basic-example) -- [Component API](#component-api) - -### Installation - -```sh -# npm -npm install @headlessui/vue - -# Yarn -yarn add @headlessui/vue -``` - -### Basic example - -```vue - - - -``` - -### Component API - -#### RadioGroup - -```html - - Pickup - Home delivery - Dine in - -``` - -##### Props - -| Prop | Type | Default | Description | -| :--------- | :------------------ | :---------- | :---------------------------------------------------------- | -| `as` | String \| Component | `div` | The element or component the `RadioGroup` should render as. | -| `value` | `T` \| undefined | `undefined` | The current selected value in the `RadioGroup`. | -| `onChange` | Function | `undefined` | The function called to update the `RadioGroup` value. | - -##### Render prop object - -- None - -#### RadioGroupOption - -```html - - Pickup - Home delivery - Dine in - -``` - -##### Props - -| Prop | Type | Default | Description | -| :------ | :------------------ | :---------- | :------------------------------------------------------------------------------------------------------------------------ | -| `as` | String \| Component | `div` | The element or component the `RadioGroup` should render as. | -| `value` | `T` \| undefined | `undefined` | The value of the current `RadioGroupOption`. The type should match the type of the `value` in the `RadioGroup` component. | - -##### Render prop object - -| Prop | Type | Description | -| :-------- | :------ | :----------------------------------------------------------------- | -| `active` | Boolean | Whether or not the option is active (using the mouse or keyboard). | -| `checked` | Boolean | Whether or not the current option is the checked value. | diff --git a/packages/@headlessui-vue/src/components/switch/README.md b/packages/@headlessui-vue/src/components/switch/README.md deleted file mode 100644 index ab01ec4..0000000 --- a/packages/@headlessui-vue/src/components/switch/README.md +++ /dev/null @@ -1,187 +0,0 @@ -## 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. - -- [Installation](#installation) -- [Basic example](#basic-example) -- [Using a custom label](#using-a-custom-label) -- [Component API](#component-api) - -## Installation - -Please note that **this library only supports Vue 3**. - -```sh -# npm -npm install @headlessui/vue - -# Yarn -yarn add @headlessui/vue -``` - -### Basic example - -Switches are built using the `Switch` component. Optionally you can also use the `SwitchGroup`, `SwitchLabel` and `SwitchDescription` 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 - - - -``` - -### 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. | -| `passive` | Boolean | `false` | When `passive` is `false`, clicking the `SwitchLabel` will not toggle the `Switch`. | - -#### SwitchDescription - -```html - - Enable notifications - - - - -``` - -##### Props - -| Prop | Type | Default | Description | -| :--- | :------------------ | :------ | :----------------------------------------------------------------- | -| `as` | String \| Component | `p` | The element or component the `SwitchDescription` 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. | diff --git a/packages/@headlessui-vue/src/components/transitions/README.md b/packages/@headlessui-vue/src/components/transitions/README.md deleted file mode 100644 index 135c55c..0000000 --- a/packages/@headlessui-vue/src/components/transitions/README.md +++ /dev/null @@ -1,369 +0,0 @@ -## Transition - -The `Transition` component lets you add enter/leave transitions to conditionally rendered elements, using CSS classes to control the actual transition styles in the different stages of the transition. - -- [Installation](#installation) -- [Basic example](#basic-example) -- [Showing and hiding content](#showing-and-hiding-content) -- [Animating transitions](#animating-transitions) -- [Co-ordinating multiple transitions](#co-ordinating-multiple-transitions) -- [Transitioning on initial mount](#transitioning-on-initial-mount) -- [Component API](#component-api) - -### Installation - -```sh -# npm -npm install @headlessui/vue - -# Yarn -yarn add @headlessui/vue -``` - -### Basic example - -The `Transition` accepts a `show` prop that controls whether the children should be shown or hidden, and a set of lifecycle props (like `enterFrom`, and `leaveTo`) that let you add CSS classes at specific phases of a transition. - -```vue - - - -``` - -### Showing and hiding content - -Wrap the content that should be conditionally rendered in a `` component, and use the `show` prop to control whether the content should be visible or hidden. - -```vue - - - -``` - -The `Transition` component will render a `div` by default, but you can use the `as` prop to render a different element instead if needed. Any other HTML attributes (like `className`) can be added directly to the `Transition` the same way they would be to regular elements. - -```vue - - - -``` - -### Animating transitions - -By default, a `Transition` will enter and leave instantly, which is probably not what you're looking for if you're using this library. - -To animate your enter/leave transitions, add classes that provide the styling for each phase of the transitions using these props: - -- **enter**: Applied the entire time an element is entering. Usually you define your duration and what properties you want to transition here, for example `transition-opacity duration-75`. -- **enterFrom**: The starting point to enter from, for example `opacity-0` if something should fade in. -- **enterTo**: The ending point to enter to, for example `opacity-100` after fading in. -- **leave**: Applied the entire time an element is leaving. Usually you define your duration and what properties you want to transition here, for example `transition-opacity duration-75`. -- **leaveFrom**: The starting point to leave from, for example `opacity-100` if something should fade out. -- **leaveTo**: The ending point to leave to, for example `opacity-0` after fading out. - -Here's an example: - -```vue - - - -``` - -In this example, the transitioning element will take 75ms to enter (that's the `duration-75` class), and will transition the opacity property during that time (that's `transition-opacity`). - -It will start completely transparent before entering (that's `opacity-0` in the `enterFrom` phase), and fade in to completely opaque (`opacity-100`) when finished (that's the `enterTo` phase). - -When the element is being removed (the `leave` phase), it will transition the opacity property, and spend 150ms doing it (`transition-opacity duration-150`). - -It will start as completely opaque (the `opacity-100` in the `leaveFrom` phase), and finish as completely transparent (the `opacity-0` in the `leaveTo` phase). - -All of these props are optional, and will default to just an empty string. - -### Co-ordinating multiple transitions - -Sometimes you need to transition multiple elements with different animations but all based on the same state. For example, say the user clicks a button to open a sidebar that slides over the screen, and you also need to fade-in a background overlay at the same time. - -You can do this by wrapping the related elements with a parent `Transition` component, and wrapping each child that needs its own transition styles with a `TransitionChild` component, which will automatically communicate with the parent `Transition` and inherit the parent's `show` state. - -```vue - - - -``` - -The `TransitionChild` component has the exact same API as the `Transition` component, but with no `show` prop, since the `show` value is controlled by the parent. - -Parent `Transition` components will always automatically wait for all children to finish transitioning before unmounting, so you don't need to manage any of that timing yourself. - -### Transitioning on initial mount - -If you want an element to transition the very first time it's rendered, set the `appear` prop to `true`. - -This is useful if you want something to transition in on initial page load, or when its parent is conditionally rendered. - -```vue - - - -``` - -### Component API - -#### Transition - -```vue - - - -``` - -##### Props - -| Prop | Type | Default | Description | -| :---------- | :------------------ | :------ | :------------------------------------------------------------------------------------ | -| `show` | Boolean | - | Whether the children should be shown or hidden. | -| `as` | String \| Component | `div` | The element or component to render in place of the `Transition` itself. | -| `appear` | Boolean | `false` | Whether the transition should run on initial mount. | -| `unmount` | Boolean | `true` | Whether the element should be `unmounted` or `hidden` based on the show state. | -| `enter` | String | `''` | Classes to add to the transitioning element during the entire enter phase. | -| `enterFrom` | String | `''` | Classes to add to the transitioning element before the enter phase starts. | -| `enterTo` | String | `''` | Classes to add to the transitioning element immediately after the enter phase starts. | -| `leave` | String | `''` | Classes to add to the transitioning element during the entire leave phase. | -| `leaveFrom` | String | `''` | Classes to add to the transitioning element before the leave phase starts. | -| `leaveTo` | String | `''` | Classes to add to the transitioning element immediately after the leave phase starts. | - -##### Events - -| Event | Description | -| :------------ | :--------------------------------------------------------------- | -| `beforeEnter` | Callback which is called before we start the enter transition. | -| `afterEnter` | Callback which is called after we finished the enter transition. | -| `beforeLeave` | Callback which is called before we start the leave transition. | -| `afterLeave` | Callback which is called after we finished the leave transition. | - -##### Render prop object - -- None - -#### TransitionChild - -```vue - - - -``` - -##### Props - -| Prop | Type | Default | Description | -| :---------- | :------------------ | :------ | :------------------------------------------------------------------------------------ | -| `as` | String \| Component | `div` | The element or component to render in place of the `TransitionChild` itself. | -| `appear` | Boolean | `false` | Whether the transition should run on initial mount. | -| `unmount` | Boolean | `true` | Whether the element should be `unmounted` or `hidden` based on the show state. | -| `enter` | String | `''` | Classes to add to the transitioning element during the entire enter phase. | -| `enterFrom` | String | `''` | Classes to add to the transitioning element before the enter phase starts. | -| `enterTo` | String | `''` | Classes to add to the transitioning element immediately after the enter phase starts. | -| `leave` | String | `''` | Classes to add to the transitioning element during the entire leave phase. | -| `leaveFrom` | String | `''` | Classes to add to the transitioning element before the leave phase starts. | -| `leaveTo` | String | `''` | Classes to add to the transitioning element immediately after the leave phase starts. | - -##### Events - -| Event | Description | -| :------------ | :--------------------------------------------------------------- | -| `beforeEnter` | Callback which is called before we start the enter transition. | -| `afterEnter` | Callback which is called after we finished the enter transition. | -| `beforeLeave` | Callback which is called before we start the leave transition. | -| `afterLeave` | Callback which is called after we finished the leave transition. | - -##### Render prop object - -- None diff --git a/packages/@headlessui-vue/src/components/transitions/transition.test.ts b/packages/@headlessui-vue/src/components/transitions/transition.test.ts index 760c870..fad8025 100644 --- a/packages/@headlessui-vue/src/components/transitions/transition.test.ts +++ b/packages/@headlessui-vue/src/components/transitions/transition.test.ts @@ -1303,11 +1303,11 @@ describe('Events', () => { let enterHookDiff = eventHandler.mock.calls[1][1] - eventHandler.mock.calls[0][1] expect(enterHookDiff).toBeGreaterThanOrEqual(enterDuration) - expect(enterHookDiff).toBeLessThanOrEqual(enterDuration * 2) + expect(enterHookDiff).toBeLessThanOrEqual(enterDuration * 3) let leaveHookDiff = eventHandler.mock.calls[3][1] - eventHandler.mock.calls[2][1] expect(leaveHookDiff).toBeGreaterThanOrEqual(leaveDuration) - expect(leaveHookDiff).toBeLessThanOrEqual(leaveDuration * 2) + expect(leaveHookDiff).toBeLessThanOrEqual(leaveDuration * 3) }) ) })