# tailwindlabs/headlessui architecture

> Architecture diagram of the GitHub repository tailwindlabs/headlessui, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tailwindlabs/headlessui
- Repository: https://github.com/tailwindlabs/headlessui

## Overview

Headless UI is a set of unstyled, accessible component libraries for React and Vue, with a companion Tailwind CSS package. The principal workflow is a consumer composing library components into an interface, where component state, interaction handling, and rendering provide accessible UI behavior. The tree shows broad component families; sampled React and Vue comboboxes illustrate the interaction layer, while React excerpts show shared rendering and positioning helpers. Most other component internals were not sampled, so their detailed call relationships are omitted.

Main entry points: [`packages/@headlessui-react/src/components/combobox/combobox.tsx`](https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-react/src/components/combobox/combobox.tsx) (React Combobox), [`packages/@headlessui-react/src/internal/floating.tsx`](https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-react/src/internal/floating.tsx) (Floating Positioning), [`packages/@headlessui-react/src/hooks/use-outside-click.ts`](https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-react/src/hooks/use-outside-click.ts) (Outside Click), [`packages/@headlessui-react/src/hooks/use-event.ts`](https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-react/src/hooks/use-event.ts) (Stable Event Hook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apis["Public UI APIs"]
  node_react_api["React Package<br/>[index.ts]"]
  node_vue_api["Vue Package<br/>[index.ts]"]
end

subgraph group_features["Interactive Components"]
  node_react_controls["React Controls"]
  node_vue_controls["Vue Controls"]
  node_react_combobox["React Combobox<br/>[combobox.tsx]"]
  node_vue_combobox["Vue Combobox<br/>[combobox.ts]"]
  node_react_dialog["React Dialog<br/>[dialog.tsx]"]
  node_vue_dialog["Vue Dialog<br/>[dialog.ts]"]
  node_react_transitions["React Transitions<br/>[transition.tsx]"]
  node_vue_transitions["Vue Transitions<br/>[transition.ts]"]
end

subgraph group_foundations["Runtime Foundations"]
  node_react_render["React Renderer<br/>[render.ts]"]
  node_react_floating["Floating Positioning<br/>[floating.tsx]"]
  node_outside_click["Outside Click"]
  node_focus_utils["Focus Utilities"]
  node_event_hook["Stable Event Hook<br/>[use-event.ts]"]
  node_latest_hook["Latest Value Hook"]
end

subgraph group_styling["Tailwind Integration"]
  node_tailwind_package["Tailwind CSS Package<br/>[index.ts]"]
end

node_consumer(("Application Developer"))

node_consumer -->|"installs"| node_react_api
node_consumer -->|"installs"| node_vue_api
node_consumer -.->|"uses"| node_tailwind_package
node_react_combobox -->|"calls"| node_outside_click
node_react_combobox -->|"provides positioning"| node_react_floating
node_react_combobox -->|"uses renderer"| node_react_render
node_vue_combobox -->|"renders components"| node_vue_controls
node_outside_click -->|"checks focus"| node_focus_utils
node_event_hook -->|"reads callback"| node_latest_hook
node_react_floating -->|"uses hook"| node_event_hook

click node_react_api "https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-react/src/index.ts"
click node_vue_api "https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-vue/src/index.ts"
click node_react_controls "https://github.com/tailwindlabs/headlessui/tree/main/packages/%40headlessui-react/src/components"
click node_vue_controls "https://github.com/tailwindlabs/headlessui/tree/main/packages/%40headlessui-vue/src/components"
click node_react_combobox "https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-react/src/components/combobox/combobox.tsx"
click node_vue_combobox "https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-vue/src/components/combobox/combobox.ts"
click node_react_dialog "https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-react/src/components/dialog/dialog.tsx"
click node_vue_dialog "https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-vue/src/components/dialog/dialog.ts"
click node_react_transitions "https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-react/src/components/transition/transition.tsx"
click node_vue_transitions "https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-vue/src/components/transitions/transition.ts"
click node_react_render "https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-react/src/utils/render.ts"
click node_react_floating "https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-react/src/internal/floating.tsx"
click node_outside_click "https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-react/src/hooks/use-outside-click.ts"
click node_focus_utils "https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-react/src/utils/focus-management.ts"
click node_event_hook "https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-react/src/hooks/use-event.ts"
click node_latest_hook "https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-react/src/hooks/use-latest-value.ts"
click node_tailwind_package "https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-tailwindcss/src/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_react_api,node_vue_api toneBlue
class node_react_controls,node_vue_controls,node_react_combobox,node_vue_combobox,node_react_dialog,node_vue_dialog,node_react_transitions,node_vue_transitions toneAmber
class node_react_render,node_react_floating,node_outside_click,node_focus_utils,node_event_hook,node_latest_hook toneMint
class node_tailwind_package toneRose
class node_consumer toneIndigo
```

## Components

### Public UI APIs

- [React Package](https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-react/src/index.ts): `packages/@headlessui-react/src/index.ts`
- [Vue Package](https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-vue/src/index.ts): `packages/@headlessui-vue/src/index.ts`

### Interactive Components

- [React Controls](https://github.com/tailwindlabs/headlessui/tree/main/packages/%40headlessui-react/src/components): `packages/@headlessui-react/src/components`
- [Vue Controls](https://github.com/tailwindlabs/headlessui/tree/main/packages/%40headlessui-vue/src/components): `packages/@headlessui-vue/src/components`
- [React Combobox](https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-react/src/components/combobox/combobox.tsx): `packages/@headlessui-react/src/components/combobox/combobox.tsx`
- [Vue Combobox](https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-vue/src/components/combobox/combobox.ts): `packages/@headlessui-vue/src/components/combobox/combobox.ts`
- [React Dialog](https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-react/src/components/dialog/dialog.tsx): `packages/@headlessui-react/src/components/dialog/dialog.tsx`
- [Vue Dialog](https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-vue/src/components/dialog/dialog.ts): `packages/@headlessui-vue/src/components/dialog/dialog.ts`
- [React Transitions](https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-react/src/components/transition/transition.tsx): `packages/@headlessui-react/src/components/transition/transition.tsx`
- [Vue Transitions](https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-vue/src/components/transitions/transition.ts): `packages/@headlessui-vue/src/components/transitions/transition.ts`

### Runtime Foundations

- [React Renderer](https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-react/src/utils/render.ts): `packages/@headlessui-react/src/utils/render.ts`
- [Floating Positioning](https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-react/src/internal/floating.tsx): `packages/@headlessui-react/src/internal/floating.tsx`
- [Outside Click](https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-react/src/hooks/use-outside-click.ts): `packages/@headlessui-react/src/hooks/use-outside-click.ts`
- [Focus Utilities](https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-react/src/utils/focus-management.ts): `packages/@headlessui-react/src/utils/focus-management.ts`
- [Stable Event Hook](https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-react/src/hooks/use-event.ts): `packages/@headlessui-react/src/hooks/use-event.ts`
- [Latest Value Hook](https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-react/src/hooks/use-latest-value.ts): `packages/@headlessui-react/src/hooks/use-latest-value.ts`

### Tailwind Integration

- [Tailwind CSS Package](https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-tailwindcss/src/index.ts): `packages/@headlessui-tailwindcss/src/index.ts`

### Other components

- **Application Developer**

## Connections

- Application Developer → React Package: installs (evidence: `README.md`)
- Application Developer → Vue Package: installs (evidence: `README.md`)
- Application Developer → Tailwind CSS Package: uses
- React Combobox → Outside Click: calls (evidence: `packages/@headlessui-react/src/components/combobox/combobox.tsx`)
- React Combobox → Floating Positioning: provides positioning (evidence: `packages/@headlessui-react/src/components/combobox/combobox.tsx`)
- React Combobox → React Renderer: uses renderer (evidence: `packages/@headlessui-react/src/components/combobox/combobox.tsx`)
- Vue Combobox → Vue Controls: renders components (evidence: `packages/@headlessui-vue/src/components/combobox/combobox.ts`)
- Outside Click → Focus Utilities: checks focus (evidence: `packages/@headlessui-react/src/hooks/use-outside-click.ts`)
- Stable Event Hook → Latest Value Hook: reads callback (evidence: `packages/@headlessui-react/src/hooks/use-event.ts`)
- Floating Positioning → Stable Event Hook: uses hook (evidence: `packages/@headlessui-react/src/internal/floating.tsx`)
