heroui-inc/heroui

🚀 Beautiful, fast and modern React UI library. (Previously NextUI)

28,765 stars TypeScript 10 components 3 connections

React UI component library with compound components and visual variants

Theme customization flows from URL parameters through state hooks to component variants, while UI components flow from primitive react-aria components through HeroUI variants to final DOM elements.

Under the hood, the system uses 2 feedback loops, 3 data pools, 4 control points to manage its runtime behavior.

Structural Verdict

A 10-component fullstack with 3 connections. 1423 files analyzed. Loosely coupled — components are relatively independent.

How Data Flows Through the System

Theme customization flows from URL parameters through state hooks to component variants, while UI components flow from primitive react-aria components through HeroUI variants to final DOM elements.

URL State Sync — nuqs parses URL parameters into theme variable state (config: base, chroma, fontFamily +4)
Variant Resolution — tailwind-variants resolves component styles based on props and context
Component Composition — Compound components compose primitive react-aria components with HeroUI styling
Theme Application — CSS variables and Tailwind classes apply final visual appearance (config: adaptiveColors, fontIds)

System Behavior

How the system actually operates at runtime — where data accumulates, what loops, what waits, and what controls what.

Data Pools

URL Parameters (state-store)
Theme customization state persisted in URL query parameters

Component Context (in-memory)
React context storing variant slots and configuration for compound components

Font CDN Cache (cache)
Browser-cached custom fonts from validated CDN URLs

Feedback Loops

Theme State Sync (polling, balancing) — Trigger: URL parameter changes. Action: Re-parse and update theme variables state. Exit: Component unmount.
Variant Re-computation (recursive, balancing) — Trigger: Component props or context changes. Action: Recompute tailwind-variants slots. Exit: Props stabilize.

Delays & Async Processing

Font Loading (async-processing, ~network dependent) — Custom fonts may flash unstyled text during load
URL State Sync (eventual-consistency, ~next render cycle) — Theme changes may lag URL updates by one render

Control Points

Theme Variables (runtime-toggle) — Controls: Visual appearance of all themed components. Default: URL-driven
Component Variants (feature-flag) — Controls: Component styling and behavior variants. Default: prop-driven
Font CDN Whitelist (threshold) — Controls: Which font CDNs are allowed for security. Default: ALLOWED_FONT_CDN_HOSTS
Turbo Build Targets (env-var) — Controls: Which packages build in parallel vs sequential. Default: tasks.build.dependsOn

Technology Stack

React (framework)
UI component framework

TypeScript (library)
Type system and development experience

Tailwind CSS (library)
Utility-first CSS framework

tailwind-variants (library)
Type-safe Tailwind variant API

react-aria-components (library)
Accessible primitive components

Turbo (build)
Monorepo build orchestration

Next.js (framework)
Documentation and demo site framework

Storybook (testing)
Component development and testing

nuqs (library)
URL-synchronized state management

Radix UI (library)
Headless component primitives for some components

Key Components

AccordionRoot (component) — Root component for collapsible accordion sections with context provider packages/react/src/components/accordion/accordion.tsx
AlertRoot (component) — Root alert component with status-based styling and icon variants packages/react/src/components/alert/alert.tsx
composeTwRenderProps (utility) — Composes Tailwind classes with react-aria-components render props packages/react/src/utils/compose.ts
accordionVariants (config) — Tailwind variant definitions for accordion component styling @heroui/styles
IconChevronDown (component) — Reusable SVG chevron icon component for dropdowns and accordions packages/react/src/components/icons.tsx
useVariablesState (hook) — URL-synced state management for theme customization variables apps/docs/src/app/themes/hooks/use-variables-state.ts
ColorPicker (type-def) — Type definitions for color picker component with format support apps/docs/src/components/color-picker/types.ts
isValidFontCdnUrl (utility) — Security validation for font CDN URLs to prevent malicious loads apps/docs/src/app/themes/utils/font-utils.ts
LockableLabel (component) — Theme editor label with lock/unlock functionality for variable constraints apps/docs/src/app/themes/components/lockable-label.tsx
getYearRange (utility) — Calendar-aware year iteration for non-Gregorian calendar systems packages/react/src/utils/calendar.ts

Sub-Modules

React Component Library (independence: high)
Core UI component library with accessibility and theming

Documentation Site (independence: medium)
Next.js documentation and demo site with theme customizer

Storybook (independence: medium)
Component development and visual testing environment

Style System (independence: high)
Tailwind variant definitions and theme utilities

Configuration

pnpm-workspace.yaml (yaml)

packages (array, unknown) — default: apps/**/**,packages/**/**

turbo.json (json)

$schema (string, unknown) — default: https://turbo.build/schema.json
globalEnv (array, unknown) — default: VERCEL_ENV,STORYBOOK_READY_ONLY,LOOPS_API_ENDPOINT,LOOPS_API_KEY,FEATUREBASE_API_ENDPOINT,FEATUREBASE_API_KEY
tasks.dev.cache (boolean, unknown) — default: false
tasks.dev.persistent (boolean, unknown) — default: true
tasks.build.dependsOn (array, unknown) — default: ^build
tasks.build.outputs (array, unknown) — default: .next/**,.source/**,dist/**,storybook-static/**
tasks.start.dependsOn (array, unknown) — default: ^build
tasks.start.outputs (array, unknown)
+7 more parameters

vercel.json (json)

$schema (string, unknown) — default: https://openapi.vercel.sh/vercel.json
github.autoJobCancelation (boolean, unknown) — default: true

Explore the interactive analysis

See the full architecture map, data flow, and code patterns visualization.

Analyze on CodeSea

Related Fullstack Repositories

Frequently Asked Questions

What is heroui used for?

React UI component library with compound components and visual variants heroui-inc/heroui is a 10-component fullstack written in TypeScript. Loosely coupled — components are relatively independent. The codebase contains 1423 files.

How is heroui architected?

heroui is organized into 4 architecture layers: React Components, Style Variants, Applications, Build Infrastructure. Loosely coupled — components are relatively independent. This layered structure keeps concerns separated and modules independent.

How does data flow through heroui?

Data moves through 4 stages: URL State Sync → Variant Resolution → Component Composition → Theme Application. Theme customization flows from URL parameters through state hooks to component variants, while UI components flow from primitive react-aria components through HeroUI variants to final DOM elements. This pipeline design keeps the data transformation process straightforward.

What technologies does heroui use?

The core stack includes React (UI component framework), TypeScript (Type system and development experience), Tailwind CSS (Utility-first CSS framework), tailwind-variants (Type-safe Tailwind variant API), react-aria-components (Accessible primitive components), Turbo (Monorepo build orchestration), and 4 more. This broad technology surface reflects a mature project with many integration points.

What system dynamics does heroui have?

heroui exhibits 3 data pools (URL Parameters, Component Context), 2 feedback loops, 4 control points, 2 delays. The feedback loops handle polling and recursive. These runtime behaviors shape how the system responds to load, failures, and configuration changes.

What design patterns does heroui use?

5 design patterns detected: Compound Components, Context-based Styling, Variant-driven Design, URL-synced State, Security Validation.

Analyzed on March 31, 2026 by CodeSea. Written by Karolina Sarna.