# heroui-inc/heroui architecture

> Architecture diagram of the GitHub repository heroui-inc/heroui, 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/heroui-inc/heroui
- Repository: https://github.com/heroui-inc/heroui

## Overview

HeroUI is a React UI component library paired with a Tailwind-oriented styles and theme package. The primary workflow is an application developer composing accessible React components, whose components apply style variants and render UI; the repository also provides AI-oriented skills and documentation scripts as a distinct authoring aid. The graph preserves broad component domains and sampled internal behavior. Many component relationships are documented only by package-level description or tree structure, so unsampled links are shown as unverified rather than asserted calls.

Main entry points: [`packages/react/src/components/index.ts`](https://github.com/heroui-inc/heroui/blob/v3/packages/react/src/components/index.ts) (Component API), [`packages/react/src/components/toast/toast.tsx`](https://github.com/heroui-inc/heroui/blob/v3/packages/react/src/components/toast/toast.tsx) (Feedback UI), [`packages/react/src/components/search-field/search-field.tsx`](https://github.com/heroui-inc/heroui/blob/v3/packages/react/src/components/search-field/search-field.tsx) (Search Field), [`packages/styles/src/components/index.ts`](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/src/components/index.ts) (Component Variants)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["React Components"]
  node_component_api["Component API<br/>[index.ts]"]
  node_forms["Form Controls"]
  node_selection["Selection Controls"]
  node_date_time["Date and Time"]
  node_overlays["Overlays"]
  node_feedback["Feedback UI<br/>[toast.tsx]"]
  node_layout["Layout and Display"]
  node_search_field["Search Field<br/>[search-field.tsx]"]
  node_sheet_drag["Sheet Drag Behavior"]
  node_toast_queue["Toast Queue<br/>[toast-queue.ts]"]
end

subgraph group_styles["Styles and Theme"]
  node_style_variants["Component Variants<br/>[index.ts]"]
  node_theme_styles["Theme Styles<br/>[index.ts]"]
end

subgraph group_runtime["Shared Runtime"]
  node_react_aria["React Aria"]
  node_hooks["React Hooks"]
  node_utils["Shared Utilities"]
  node_icons["Icon Components<br/>[icons.tsx]"]
end

subgraph group_ai["AI Skills"]
  node_skills["Agent Skills"]
  node_migration_skills["Migration Skills"]
  node_native_skills["Native Skills"]
end

node_developer(("React Developer"))
node_application["Rendered Application UI"]

node_developer -->|"composes"| node_component_api
node_component_api -.->|"exposes"| node_forms
node_component_api -.->|"exposes"| node_selection
node_component_api -.->|"exposes"| node_date_time
node_component_api -.->|"exposes"| node_overlays
node_component_api -.->|"exposes"| node_feedback
node_component_api -.->|"exposes"| node_layout
node_search_field -->|"renders with"| node_react_aria
node_search_field -->|"uses variants"| node_style_variants
node_search_field -->|"renders icon"| node_icons
node_search_field -->|"resolves classes"| node_utils
node_sheet_drag -->|"reads props"| node_react_aria
node_sheet_drag -->|"animates values"| node_utils
node_feedback -->|"uses queue"| node_toast_queue
node_feedback -->|"measures height"| node_hooks
node_feedback -.->|"uses variants"| node_style_variants
node_feedback -->|"renders icons"| node_icons
node_feedback -.->|"renders"| node_application
node_style_variants -.->|"contributes styles"| node_theme_styles
node_forms -.->|"builds on"| node_react_aria
node_selection -.->|"builds on"| node_react_aria
node_date_time -.->|"builds on"| node_react_aria
node_overlays -.->|"builds on"| node_react_aria
node_layout -.->|"renders"| node_application
node_developer -.->|"consults"| node_skills
node_developer -.->|"consults"| node_migration_skills
node_developer -.->|"consults"| node_native_skills

click node_component_api "https://github.com/heroui-inc/heroui/blob/v3/packages/react/src/components/index.ts"
click node_forms "https://github.com/heroui-inc/heroui/tree/v3/packages/react/src/components"
click node_selection "https://github.com/heroui-inc/heroui/tree/v3/packages/react/src/components"
click node_date_time "https://github.com/heroui-inc/heroui/tree/v3/packages/react/src/components"
click node_overlays "https://github.com/heroui-inc/heroui/tree/v3/packages/react/src/components"
click node_feedback "https://github.com/heroui-inc/heroui/blob/v3/packages/react/src/components/toast/toast.tsx"
click node_layout "https://github.com/heroui-inc/heroui/tree/v3/packages/react/src/components"
click node_search_field "https://github.com/heroui-inc/heroui/blob/v3/packages/react/src/components/search-field/search-field.tsx"
click node_sheet_drag "https://github.com/heroui-inc/heroui/blob/v3/packages/react/src/components/sheet/use-sheet-handle-drag.ts"
click node_toast_queue "https://github.com/heroui-inc/heroui/blob/v3/packages/react/src/components/toast/toast-queue.ts"
click node_style_variants "https://github.com/heroui-inc/heroui/blob/v3/packages/styles/src/components/index.ts"
click node_theme_styles "https://github.com/heroui-inc/heroui/blob/v3/packages/styles/src/index.ts"
click node_hooks "https://github.com/heroui-inc/heroui/tree/v3/packages/react/src/hooks"
click node_utils "https://github.com/heroui-inc/heroui/tree/v3/packages/react/src/utils"
click node_icons "https://github.com/heroui-inc/heroui/blob/v3/packages/react/src/components/icons.tsx"
click node_skills "https://github.com/heroui-inc/heroui/tree/v3/skills/heroui-react/scripts"
click node_migration_skills "https://github.com/heroui-inc/heroui/tree/v3/skills/heroui-migration/scripts"
click node_native_skills "https://github.com/heroui-inc/heroui/tree/v3/skills/heroui-native/scripts"

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_component_api,node_forms,node_selection,node_date_time,node_overlays,node_feedback,node_layout,node_search_field,node_sheet_drag,node_toast_queue,node_application toneBlue
class node_style_variants,node_theme_styles toneAmber
class node_react_aria,node_hooks,node_utils,node_icons toneMint
class node_skills,node_migration_skills,node_native_skills toneRose
class node_developer toneIndigo
```

## Components

### React Components

- [Component API](https://github.com/heroui-inc/heroui/blob/v3/packages/react/src/components/index.ts): `packages/react/src/components/index.ts`
- [Form Controls](https://github.com/heroui-inc/heroui/tree/v3/packages/react/src/components): `packages/react/src/components`
- [Selection Controls](https://github.com/heroui-inc/heroui/tree/v3/packages/react/src/components): `packages/react/src/components`
- [Date and Time](https://github.com/heroui-inc/heroui/tree/v3/packages/react/src/components): `packages/react/src/components`
- [Overlays](https://github.com/heroui-inc/heroui/tree/v3/packages/react/src/components): `packages/react/src/components`
- [Feedback UI](https://github.com/heroui-inc/heroui/blob/v3/packages/react/src/components/toast/toast.tsx): `packages/react/src/components/toast/toast.tsx`
- [Layout and Display](https://github.com/heroui-inc/heroui/tree/v3/packages/react/src/components): `packages/react/src/components`
- [Search Field](https://github.com/heroui-inc/heroui/blob/v3/packages/react/src/components/search-field/search-field.tsx): `packages/react/src/components/search-field/search-field.tsx`
- [Sheet Drag Behavior](https://github.com/heroui-inc/heroui/blob/v3/packages/react/src/components/sheet/use-sheet-handle-drag.ts): `packages/react/src/components/sheet/use-sheet-handle-drag.ts`
- [Toast Queue](https://github.com/heroui-inc/heroui/blob/v3/packages/react/src/components/toast/toast-queue.ts): `packages/react/src/components/toast/toast-queue.ts`

### Styles and Theme

- [Component Variants](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/src/components/index.ts): `packages/styles/src/components/index.ts`
- [Theme Styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/src/index.ts): `packages/styles/src/index.ts`

### Shared Runtime

- **React Aria**
- [React Hooks](https://github.com/heroui-inc/heroui/tree/v3/packages/react/src/hooks): `packages/react/src/hooks`
- [Shared Utilities](https://github.com/heroui-inc/heroui/tree/v3/packages/react/src/utils): `packages/react/src/utils`
- [Icon Components](https://github.com/heroui-inc/heroui/blob/v3/packages/react/src/components/icons.tsx): `packages/react/src/components/icons.tsx`

### AI Skills

- [Agent Skills](https://github.com/heroui-inc/heroui/tree/v3/skills/heroui-react/scripts): `skills/heroui-react/scripts`
- [Migration Skills](https://github.com/heroui-inc/heroui/tree/v3/skills/heroui-migration/scripts): `skills/heroui-migration/scripts`
- [Native Skills](https://github.com/heroui-inc/heroui/tree/v3/skills/heroui-native/scripts): `skills/heroui-native/scripts`

### Other components

- **React Developer**
- **Rendered Application UI**

## Connections

- React Developer → Component API: composes (evidence: `README.md`)
- Component API → Form Controls: exposes
- Component API → Selection Controls: exposes
- Component API → Date and Time: exposes
- Component API → Overlays: exposes
- Component API → Feedback UI: exposes
- Component API → Layout and Display: exposes
- Search Field → React Aria: renders with (evidence: `packages/react/src/components/search-field/search-field.tsx`)
- Search Field → Component Variants: uses variants (evidence: `packages/react/src/components/search-field/search-field.tsx`)
- Search Field → Icon Components: renders icon (evidence: `packages/react/src/components/search-field/search-field.tsx`)
- Search Field → Shared Utilities: resolves classes (evidence: `packages/react/src/components/search-field/search-field.tsx`)
- Sheet Drag Behavior → React Aria: reads props (evidence: `packages/react/src/components/sheet/use-sheet-handle-drag.ts`)
- Sheet Drag Behavior → Shared Utilities: animates values (evidence: `packages/react/src/components/sheet/use-sheet-handle-drag.ts`)
- Feedback UI → Toast Queue: uses queue (evidence: `packages/react/src/components/toast/toast.tsx`)
- Feedback UI → React Hooks: measures height (evidence: `packages/react/src/components/toast/toast.tsx`)
- Feedback UI → Component Variants: uses variants
- Feedback UI → Icon Components: renders icons (evidence: `packages/react/src/components/toast/toast.tsx`)
- Feedback UI → Rendered Application UI: renders
- Component Variants → Theme Styles: contributes styles
- Form Controls → React Aria: builds on
- Selection Controls → React Aria: builds on
- Date and Time → React Aria: builds on
- Overlays → React Aria: builds on
- Layout and Display → Rendered Application UI: renders
- React Developer → Agent Skills: consults
- React Developer → Migration Skills: consults
- React Developer → Native Skills: consults
