HeroUI

v3.0.0-alpha.32

Card component redesign, CloseButton, MCP Server for AI assistants

October 1, 2025

This release adds AI development tools, updates the Card component API, and improves the developer experience.

Installation

Update to the latest version:

npm i @heroui/styles@alpha @heroui/react@alpha
pnpm add @heroui/styles@alpha @heroui/react@alpha
yarn add @heroui/styles@alpha @heroui/react@alpha
bun add @heroui/styles@alpha @heroui/react@alpha

What's New

MCP Server

HeroUI now includes an MCP server that lets AI assistants like Cursor, Claude Code, and VS Code Copilot access HeroUI v3 documentation and component information directly.

Quick Setup:

Cursor

Install in Cursor

Or manually add to Cursor Settings → Tools → MCP Servers:

{
  "mcpServers": {
    "heroui-react": {
      "command": "npx",
      "args": ["-y", "@heroui/react-mcp@latest"]
    }
  }
}

Claude Code

Run this command in your terminal:

claude mcp add heroui-react -- npx -y @heroui/react-mcp@latest

Learn more

Card Component API Redesign

The Card component has been updated with a new variant system that makes it more flexible.

Breaking Changes:

  • Replaced surface prop with new variant system
  • Removed Card.Image, Card.Details, and Card.CloseButton (use composition instead)
  • New variants: flat, outlined, elevated, filled

Before:

<Card surface="1">
  <Card.Image src="/image.jpg" />
  <Card.Details>
    <Card.Title>Old Card</Card.Title>
  </Card.Details>
</Card>

After:

<Card variant="outlined">
  <Card.Header>
    <img src="/image.jpg" alt="Card image" />
  </Card.Header>
  <Card.Body>
    <Card.Title>New Card</Card.Title>
  </Card.Body>
</Card>

New Features:

  • Horizontal layout support
  • Avatar integration
  • Background image support
  • Improved accessibility with semantic HTML

View Card documentation

CloseButton Component

Added a CloseButton component for closing dialogs, modals, and other dismissible elements.

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

// Basic usage
<CloseButton onPress={() => console.log("Closed")} />

// With custom icon
<CloseButton>
  <XMarkIcon className="size-4" />
</CloseButton>

Documentation Improvements

UI for Agents

Component Documentation

  • Card: Rewrote documentation with anatomy, variants, and more examples
  • Switch: Added anatomy diagrams and better examples
  • CloseButton: New documentation with usage examples

Migration Guide

Card Component Migration

  1. Update variant prop:

    • surface="1" → variant="flat"
    • surface="2" → variant="outlined"
    • surface="3" → variant="elevated"
    • surface="4" → variant="filled"
    • Custom surfaces → Use new variant system

  2. Update component structure:

    • Replace Card.Image with <img> in Card.Header
    • Replace Card.Details with Card.Body
    • Move Card.CloseButton to use new CloseButton component

  3. Update imports:

    // Add CloseButton if needed
import {Card, CloseButton} from "@heroui/react";

Contributors

Thanks to everyone who contributed to this release!