HeroUI v3

[jrgarciadev]

HeroUI v3 Alpha is here - a complete re-imagining built for React 19, Tailwind v4, and design-first workflows. ⚠️ (alpha release, expect changes)

Hey folks! We've been heads-down rebuilding HeroUI from the ground up, and today we're thrilled to open the v3 Alpha. It's now in alpha, and we're inviting everyone still on v2 to explore what's new and why this release sets the foundation for the future.

This discussion covers the why, highlights the big improvements, and outlines how you can start exploring or migrating today.

---

Why HeroUI v3?

• Future-proof styling: Built for React Server Components, Next.js App Router, React 19, and first-class Tailwind v4 support.
• Design-first workflow: Every component was designed in Figma before implementation, ensuring pixel-perfect parity.
  → [HeroUI v3 Figma Kit](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
• DX you’ve been asking for: We swapped Framer Motion for handcrafted CSS animations, moved to [React Aria Components](https://react-spectrum.adobe.com/react-aria/components.html), and removed the global HeroUIProvider.
• Simplified packages: Only two remain - @heroui/react and @heroui/styles - with a custom Rollup build for better tree-shaking, smaller bundles, and faster installs.
• Composable by default: v3 embraces compound components instead of prop-heavy APIs, letting you assemble exactly what you need with minimal overrides.

📘 Explore the full vision and design principles:

• [Introduction to HeroUI v3](https://v3.heroui.com/docs/introduction)
• [Design principles](https://v3.heroui.com/docs/design-principles)
• [Roadmap](https://herouiv3.featurebase.app/roadmap)

---

Compound Pattern Over Props

In v2 we leaned on prop bags and classNames helpers.
v3 exposes every building block so you can compose, restyle, or replace any internal piece.

// v2 Accordion
import {Accordion, AccordionItem} from "@heroui/react";

export default function App() {
  return (
    <Accordion>
      <AccordionItem key="1" title="Accordion 1">
        Lorem ipsum dolor sit amet…
      </AccordionItem>
    </Accordion>
  );
}

// v3 Accordion
import {Accordion} from "@heroui/react";
import {Icon} from "@iconify/react";

const items = [/* … */];

export function Basic() {
  return (
    <Accordion.Root className="w-full max-w-md">
      {items.map((item, index) => (
        <Accordion.Item key={index}>
          <Accordion.Heading>
            <Accordion.Trigger>
              {item.icon ? <Icon className="mr-3 size-4" icon={item.icon} /> : null}
              {item.title}
              <Accordion.Indicator>
                <Icon icon="gravity-ui:chevron-down" />
              </Accordion.Indicator>
            </Accordion.Trigger>
          </Accordion.Heading>
          <Accordion.Panel>
            <Accordion.Body>{item.content}</Accordion.Body>
          </Accordion.Panel>
        </Accordion.Item>
      ))}
    </Accordion.Root>
  );
}

The same story plays out across the library. For example, the Popover now uses a slot-based API instead of prop drilling:

// v2 Popover
import {Popover, PopoverTrigger, PopoverContent, Button} from "@heroui/react";

export default function App() {
  return (
    <Popover placement="right">
      <PopoverTrigger>
        <Button>Open Popover</Button>
      </PopoverTrigger>
      <PopoverContent>
        <div className="px-1 py-2">
          <div className="text-small font-bold">Popover Content</div>
          <div className="text-tiny">This is the popover content</div>
        </div>
      </PopoverContent>
    </Popover>
  );
}

// v3 Popover
import {Button, Popover} from "@heroui/react";

export function PopoverBasic() {
  return (
    <div className="flex items-center gap-4">
      <Popover.Root>
        <Button>Click me</Button>
        <Popover.Content>
          <Popover.Dialog>
            <Popover.Heading>Popover Title</Popover.Heading>
            <p className="text-muted mt-2 text-sm">
              This is the popover content. You can put any content here.
            </p>
          </Popover.Dialog>
        </Popover.Content>
      </Popover.Root>
    </div>
  );
}

---

Styling & Theming Superpowers

• No Tailwind plugin required: Install Tailwind, import @heroui/styles, and you’re done. Compare the new [Quick Start](https://v3.heroui.com/docs/quick-start) with the old [v2 installation guide](https://www.heroui.com/docs/guide/installation).
• BEM meets Tailwind: We ship slot classes that you can override globally or per component. Example:

@layer components {
  .button {
    @apply bg-purple-500 text-white hover:bg-purple-600;
  }
  .button--icon-only {
    @apply rounded-lg bg-blue-500;
  }
}

• Extend with tailwind-variants: Compose on top of our exports while keeping type safety.

import {Button, buttonVariants} from "@heroui/react";
import {tv} from "tailwind-variants";

const myButtonVariants = tv({
  base: "text-md font-semibold shadow-md data-[pending=true]:opacity-40",
  defaultVariants: {radius: "full", variant: "primary"},
  extend: buttonVariants,
  variants: {
    radius: {full: "rounded-full", lg: "rounded-lg"},
    variant: {primary: "text-white dark:bg-white/10"},
  },
});

• Reusables folder (coming soon): Generate reusable component wrappers (/heroui/accordion.tsx, /heroui/button.tsx, …) so your app imports a concise API while the verbose markup lives in one place.

---

Built for Performance, RSC, and the AI Age

• Zero global provider - theming now flows through CSS variables, making Server Components and streaming first-class.
• Smaller bundles, faster builds, and CSS-only animations (Framer Motion removed).
• React 19-ready and powered by React Aria Components for accessibility without extra wiring.
• Each docs page includes llms.txt and a custom [HeroUI MCP Server](https://v3.heroui.com/docs/ui-for-agents/mcp-server) so AI agents (or you!) can generate and refactor code confidently.

---

Migration Game Plan

1. Start experimenting

   • Follow the [Quick Start](https://v3.heroui.com/docs/quick-start).
   • Browse live examples in the [Storybook](https://storybook-v3.heroui.com/) and docs playgrounds.

2. Map components

   • Each doc page includes v2 vs v3 guidance, new props, and slot names.
   • We’re preparing an upgrade [MCP](https://v3.heroui.com/docs/ui-for-agents/mcp-server) tools and codemod to rewrite common v2 patterns into v3 structures.

3. Design alignment

   • Align with the [Figma kit](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3) before coding - exactly how our team builds v3.

4. Share feedback

   • v3 is still alpha. Expect visual and interaction tweaks as we bring back more of the beloved v2 personality while keeping the new flexibility.

---

FAQ

• Is v3 backward compatible with v2?
  No. The move to compound components, Tailwind-first styling, and new packages means this is a breaking change. We’ll provide codemods and MCP recipes to ease the migration.

• Will v2 keep getting fixes?
  We’ll continue addressing critical issues, but new investment goes into v3. Bug fixes will land in Tailwind-based components whenever possible.

• Does v3 fix Next.js 13+ / RSC issues?
  Yes. Thanks to our custom build process, you no longer need to add "use client" on top of your files.

• What about bundle size and performance?
  Expect smaller bundles, less JavaScript executed at runtime (framer-motion removed), and faster mounts thanks to CSS animations and improved tree-shaking.

---

Resources

• Docs: https://v3.heroui.com/docs
• Design principles: https://v3.heroui.com/docs/design-principles
• Roadmap: https://herouiv3.featurebase.app/roadmap
• Storybook: https://storybook-v3.heroui.com/
• Changelog (latest alpha): https://v3.heroui.com/docs/changelog/v3-0-0-alpha-35
• Figma kit: https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3
• Tailwind playground demo: https://play.tailwindcss.com/Ioomj2xdce
• MCP server docs: https://v3.heroui.com/docs/ui-for-agents/mcp-server

---

We Need Your Eyes & Ideas

Try the alpha, stress-test the compound APIs, and tell us what still feels rough. Before the first RC we’ll roll out the upgrade codemod, polish the MCP workflows, and ship the refreshed visual language. Your feedback now directly shapes those milestones.

Thanks for supporting us! 🙌

[LeeWio]

Looking forward to the release of the alpha version of HeroUI CLI! 😄🚀🎉

[splicebison]

Could you clarify the reasoning for the style choice perhaps? It's not clear to me the benefit of Tailwind here when @apply and BEM classes are being used throughout the codebase. Atomic styles being the primary benefit of Tailwind are rendered useless with this methodology as the tailwind classes will end up in duplication thus impacting CSS bundle size.