or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

form-components.md index.md overlay-components.md selection-components.md utility-components.md

tile.json

tessl/npm-headlessui--react

A set of completely unstyled, fully accessible UI components for React, designed to integrate beautifully with Tailwind CSS.

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/@headlessui/react@2.2.x

To install, run

npx @tessl/cli install tessl/npm-headlessui--react@2.2.0

Headless UI React

Headless UI is a set of completely unstyled, fully accessible UI components for React, designed to integrate beautifully with Tailwind CSS. The components provide the behavioral logic and accessibility features for complex UI patterns while giving developers complete control over styling.

Package Information

Package Name: @headlessui/react
Package Type: npm
Language: TypeScript

Installation:

npm install @headlessui/react

Peer Dependencies: React 18+ and React DOM 18+

Core Imports

import {
  Button,
  Checkbox,
  CloseButton,
  Input,
  Select,
  Textarea,
  Dialog,
  DialogPanel,
  DialogBackdrop,
  DialogTitle,
  Menu,
  MenuButton,
  MenuItems,
  MenuItem,
  Combobox,
  ComboboxInput,
  ComboboxButton,
  ComboboxOptions,
  ComboboxOption,
  Listbox,
  ListboxButton,
  ListboxOptions,
  ListboxOption,
  Popover,
  PopoverButton,
  PopoverPanel,
  Switch,
  TabGroup,
  TabList,
  Tab,
  TabPanels,
  TabPanel,
  Radio,
  RadioGroup,
  RadioGroupOption,
  Disclosure,
  DisclosureButton,
  DisclosurePanel,
  Field,
  Fieldset,
  Legend,
  Label,
  Description,
  FocusTrap,
  Portal,
  Transition,
  DataInteractive,
  useClose
} from "@headlessui/react";

For CommonJS:

const {
  Button,
  Checkbox,
  CloseButton,
  Input,
  Select,
  Textarea,
  Dialog,
  DialogPanel,
  DialogBackdrop,
  DialogTitle,
  Menu,
  MenuButton,
  MenuItems,
  MenuItem,
  Combobox,
  ComboboxInput,
  ComboboxButton,
  ComboboxOptions,
  ComboboxOption,
  Listbox,
  ListboxButton,
  ListboxOptions,
  ListboxOption,
  Popover,
  PopoverButton,
  PopoverPanel,
  Switch,
  TabGroup,
  TabList,
  Tab,
  TabPanels,
  TabPanel,
  Radio,
  RadioGroup,    
  RadioGroupOption,
  Disclosure,
  DisclosureButton,
  DisclosurePanel,
  Field,
  Fieldset,
  Legend,
  Label,
  Description,
  FocusTrap,
  Portal,
  Transition,
  DataInteractive,
  useClose
} = require("@headlessui/react");

Basic Usage

import { useState } from "react";
import { Dialog, DialogPanel, DialogTitle } from "@headlessui/react";

function MyDialog() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Open dialog</button>
      <Dialog open={isOpen} onClose={() => setIsOpen(false)}>
        <div className="fixed inset-0 bg-black/30" aria-hidden="true" />
        <div className="fixed inset-0 flex w-screen items-center justify-center p-4">
          <DialogPanel className="max-w-lg space-y-4 bg-white p-6 rounded-lg">
            <DialogTitle className="font-bold">Confirm Action</DialogTitle>
            <p>Are you sure you want to continue?</p>
            <div className="flex gap-4">
              <button onClick={() => setIsOpen(false)}>Cancel</button>
              <button onClick={() => setIsOpen(false)}>Confirm</button>
            </div>
          </DialogPanel>
        </div>
      </Dialog>
    </>
  );
}

Architecture

Headless UI follows several key design principles:

Unstyled by Design: Components come with no default styles, giving complete visual control
Fully Accessible: All components follow WAI-ARIA guidelines with proper ARIA attributes and keyboard navigation
Polymorphic Components: All components support the
```
as
```
prop to render as different HTML elements or custom components
Type-Safe: Comprehensive TypeScript definitions with generic type parameters where appropriate
Render Props Pattern: Interactive components provide render props with current state (hover, focus, active, disabled, etc.)
Form Integration: Form components support controlled/uncontrolled patterns and standard form attributes

Capabilities

Form Components

Basic form controls including buttons, inputs, checkboxes, selects, textareas, and switches with built-in accessibility and interaction states.

// Basic button with interaction states
function Button(props: ButtonProps): JSX.Element;

// Checkbox with indeterminate state support
function Checkbox(props: CheckboxProps): JSX.Element;

// Text input with validation states
function Input(props: InputProps): JSX.Element;

// Native select element with enhanced styling
function Select(props: SelectProps): JSX.Element;

// Textarea element with form integration
function Textarea(props: TextareaProps): JSX.Element;

// Toggle switch component
function Switch(props: SwitchProps): JSX.Element;

Form Components

Selection Components

Advanced selection interfaces including comboboxes, listboxes, radio groups, and native selects with keyboard navigation and accessibility.

// Autocomplete combobox with filtering
function Combobox<TValue>(props: ComboboxProps<TValue>): JSX.Element;

// Multi-select capable listbox
function Listbox<TValue>(props: ListboxProps<TValue>): JSX.Element;

// Radio button group for single selection
function RadioGroup<TValue>(props: RadioGroupProps<TValue>): JSX.Element;

Selection Components

Overlay Components

Modal dialogs, popovers, and tooltips that appear on top of the main content with focus management and portal rendering.

// Modal dialog with focus trapping
function Dialog(props: DialogProps): JSX.Element;

// Floating popover interface
function Popover(props: PopoverProps): JSX.Element;

// Tooltip component (commented out in v2.2.7)
// function Tooltip(props: TooltipProps): JSX.Element;

Overlay Components

Navigation Components

Components for organizing and navigating content including menus, tabs, and disclosure panels.

// Dropdown menu for actions
function Menu(props: MenuProps): JSX.Element;

// Tab interface for content organization
function TabGroup(props: TabGroupProps): JSX.Element;

// Collapsible disclosure panel
function Disclosure(props: DisclosureProps): JSX.Element;

Navigation Components

Utility Components

Supporting components and utilities including focus traps, portals, labels, descriptions, transitions, and hooks.

// Focus management utility
function FocusTrap(props: FocusTrapProps): JSX.Element;

// Portal for rendering outside DOM tree
function Portal(props: PortalProps): JSX.Element;

// CSS transition wrapper
function Transition(props: TransitionProps): JSX.Element;

// Form label with automatic association
function Label(props: LabelProps): JSX.Element;

// Description text with automatic association
function Description(props: DescriptionProps): JSX.Element;

// Hook for closing containing components
function useClose(): () => void;

Utility Components

Common Patterns

Render Props

All interactive components provide render props with current interaction state:

<Button>
  {({ hover, focus, active, disabled }) => (
    <span 
      className={`
        px-4 py-2 rounded 
        ${hover ? 'bg-blue-100' : 'bg-white'}
        ${focus ? 'ring-2 ring-blue-500' : ''}
        ${active ? 'bg-blue-200' : ''}
        ${disabled ? 'opacity-50 cursor-not-allowed' : ''}
      `}
    >
      Click me
    </span>
  )}
</Button>

Polymorphic Components

Use the

as

prop to render components as different elements:

// Render as a link instead of button
<Button as="a" href="/dashboard">
  Dashboard
</Button>

// Render as a custom component
<Button as={CustomLink} to="/profile">
  Profile
</Button>

Form Integration

Form components integrate with standard HTML form patterns:

<form>
  <Field>
    <Label>Username</Label>
    <Input name="username" required />
    <Description>Enter your username</Description>
  </Field>
  
  <Field>
    <Checkbox name="newsletter" value="yes">
      Subscribe to newsletter
    </Checkbox>
  </Field>
</form>

Types

// Common render prop types
interface InteractionState {
  hover: boolean;
  focus: boolean;
  active: boolean;
  disabled: boolean;
}

// Polymorphic component props
interface PolymorphicProps<TTag extends keyof JSX.IntrinsicElements = 'div'> {
  as?: TTag;
  children?: React.ReactNode | ((props: any) => React.ReactNode);
}

// Focus trap features enum
enum FocusTrapFeatures {
  None = 0,
  InitialFocus = 1,
  TabLock = 2,
  FocusLock = 4,
  RestoreFocus = 8,
  AutoFocus = 16
}

// Comparison function type for value-based components
type ByComparator<T> = 
  | ((a: T, z: T) => boolean)
  | keyof T
  | null;

Migration and Deprecation Notes

Deprecated Components (v2.x)

Some components have been deprecated in favor of more flexible alternatives:

Form Organization:

```
SwitchGroup
```
→ Use
```
Field
```
component instead
```
SwitchLabel
```
→ Use
```
Label
```
component instead
```
SwitchDescription
```
→ Use
```
Description
```
component instead

Radio Groups:

```
RadioGroupLabel
```
→ Use
```
Label
```
component instead
```
RadioGroupDescription
```
→ Use
```
Description
```
component instead

Legacy Subcomponent Patterns:

```
Combobox.Input
```
→ Use
```
ComboboxInput
```
component instead
```
Combobox.Button
```
→ Use
```
ComboboxButton
```
component instead
```
Combobox.Options
```
→ Use
```
ComboboxOptions
```
component instead
```
Combobox.Option
```
→ Use
```
ComboboxOption
```
component instead
```
Menu.Button
```
→ Use
```
MenuButton
```
component instead
```
Menu.Items
```
→ Use
```
MenuItems
```
component instead
```
Menu.Item
```
→ Use
```
MenuItem
```
component instead
```
Listbox.Button
```
→ Use
```
ListboxButton
```
component instead
```
Listbox.Options
```
→ Use
```
ListboxOptions
```
component instead
```
Listbox.Option
```
→ Use
```
ListboxOption
```
component instead
```
Dialog.Panel
```
→ Use
```
DialogPanel
```
component instead
```
Dialog.Title
```
→ Use
```
DialogTitle
```
component instead
```
Disclosure.Button
```
→ Use
```
DisclosureButton
```
component instead
```
Disclosure.Panel
```
→ Use
```
DisclosurePanel
```
component instead

Version Notes

This documentation covers @headlessui/react v2.2.7. Some features may differ in earlier versions:

Standalone component exports (e.g.,
```
ComboboxInput
```
,
```
MenuButton
```
) were introduced in v2.x
The
```
as
```
prop and polymorphic behavior is available in all v2.x components
Form integration features (
```
Field
```
,
```
Fieldset
```
, etc.) are v2.x additions

Future Components

Some components are planned but not yet available:

```
Tooltip
```
component is commented out in the current version but may be enabled in future releases

Version

Tile

Files

tessl/npm-headlessui--react

To install, run

index.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Headless UI React

Package Information

Core Imports

Basic Usage

Architecture

Capabilities

Form Components

Selection Components

Overlay Components

Navigation Components

Utility Components

Common Patterns

Render Props

Polymorphic Components

Form Integration

Types

Migration and Deprecation Notes

Deprecated Components (v2.x)

Version Notes

Future Components

index.mddocs/