Heroui

HeroUI v3

An open-source UI component library for React (web) and React Native (mobile). Built on Tailwind CSS v4 and React Aria Components. Provides 75+ accessible, customizable web components and 40+ native components.

Technology Stack

Quick Setup

React (Web)

npm i @heroui/react @heroui/styles

/* globals.css — order matters */
@import "tailwindcss";
@import "@heroui/styles";

import { Button } from "@heroui/react";

function App() {
  return <Button>Click me</Button>;
}

React Native

npm install heroui-native react-native-reanimated@^4.1.1 react-native-gesture-handler@^2.28.0 react-native-worklets@^0.5.1 react-native-safe-area-context@^5.6.0 react-native-svg@^15.12.1 tailwind-variants@^3.2.2 tailwind-merge@^3.4.0

/* global.css */
@import "tailwindcss";
@import "uniwind";
@import "heroui-native/styles";
@source "./node_modules/heroui-native/lib";

import { HeroUINativeProvider } from "heroui-native";
import { GestureHandlerRootView } from "react-native-gesture-handler";
import { Button } from "heroui-native";

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <HeroUINativeProvider>
        <Button => console.log("Pressed!")}>Get Started</Button>
      </HeroUINativeProvider>
    </GestureHandlerRootView>
  );
}

For detailed setup instructions, see react-setup.md and native-setup.md.

Component Architecture

HeroUI v3 uses compound component composition with dot notation:

<Modal>
  <Button>Open</Button>
  <Modal.Backdrop>
    <Modal.Container>
      <Modal.Dialog>
        <Modal.Header>
          <Modal.Heading>Title</Modal.Heading>
        </Modal.Header>
        <Modal.Body>Content</Modal.Body>
        <Modal.Footer>
          <Button slot="close">Close</Button>
        </Modal.Footer>
      </Modal.Dialog>
    </Modal.Container>
  </Modal.Backdrop>
</Modal>

Three Import Patterns

// 1. Compound (recommended)
<Alert>
  <Alert.Icon />
  <Alert.Content>
    <Alert.Title>Success</Alert.Title>
  </Alert.Content>
</Alert>

// 2. With .Root suffix
<Alert.Root>
  <Alert.Icon />
</Alert.Root>

// 3. Named exports
import { AlertRoot, AlertIcon, AlertContent, AlertTitle } from "@heroui/react";

Type Imports

import type { ButtonRootProps, AvatarRootProps } from "@heroui/react";

React Web Components (75+)

For component anatomy, props, and usage patterns, see react-components.md.

React Native Components (40+)

For native component details, see native-components.md.

Styling System

HeroUI v3 provides three styling approaches:

1. BEM Classes

<button className="button button--primary button--lg">Click</button>

Class pattern: .{block}, .{block}__{element}, .{block}--{modifier}

2. Variant Functions (Type-Safe)

import { buttonVariants } from "@heroui/styles";

<a className={buttonVariants({ variant: "primary", size: "lg" })} href="/about">
  About
</a>

Variant functions are framework-agnostic — usable with Vue, Svelte, vanilla HTML.

3. Tailwind CSS Classes + className Prop

<Button className="rounded-full shadow-lg">Styled</Button>

Custom Variants

import { buttonVariants, tv } from "@heroui/styles";

const myButton = tv({
  extend: buttonVariants,
  base: "font-semibold shadow-md",
  variants: {
    radius: { lg: "rounded-lg", md: "rounded-md" },
  },
});

render Prop for Custom Elements

<Button
  render={(domProps, { isPressed }) => (
    <motion.button {...domProps} animate={{ scale: isPressed ? 0.9 : 1 }} />
  )}
>
  Animated
</Button>

For theming, CSS variables, dark mode, custom themes, and component-level overrides, see theming-and-styling.md.

Common Prop Patterns

Interactive States (Data Attributes)

Event Handlers

HeroUI uses React Aria's press events, not native click events:

<Button => console.log("pressed")} />

Overlay State Management

import { useOverlayState } from "@heroui/react";

const state = useOverlayState({ defaultOpen: false });
// state.isOpen, state.open(), state.close(), state.toggle(), state.setOpen()

Form Validation

import { Form, TextField, Button } from "@heroui/react";

<Form validationBehavior="aria"
  <TextField name="email" isRequired>
    <Label>Email</Label>
    <Input />
    <FieldError />
  </TextField>
  <Button type="submit">Submit</Button>
</Form>

Two validation modes: "native" (blocks submission) and "aria" (realtime errors).

Documentation Resources