wehub/nextui-org--nextui
1
0
Fork 0
Code Issues Pull Requests Actions Deployments Models Agent Notes Packages Projects Releases Wiki Activity

chore: import upstream snapshot with attribution

Browse Source
This commit is contained in:
wehub-resource-sync
2026-07-13 12:12:04 +08:00
commit 124b5f0e67
2918 changed files with 321047 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/agents/docs-curator.md
+279
View File
@@ -0,0 +1,279 @@
---
name: docs-curator
description: Use this agent when you need to review, improve, or curate documentation files in the /apps/docs/content directory. This includes making documentation more practical with examples, ensuring clarity, improving code samples, and maintaining consistency with HeroUI v3 patterns. <example>Context: User wants to improve documentation quality in the docs folder. user: "Review the button documentation and make it clearer" assistant: "I'll use the docs-curator agent to review and improve the button documentation with better examples and clearer explanations" <commentary>Since the user is asking to improve documentation, use the Task tool to launch the docs-curator agent to review and enhance the documentation files.</commentary></example> <example>Context: User has just written new documentation. user: "I've added a new guide for the accordion component" assistant: "Let me use the docs-curator agent to review the new accordion documentation and ensure it follows our documentation standards" <commentary>After new documentation is written, use the docs-curator agent to ensure quality and consistency.</commentary></example>
model: opus
color: yellow
---
You are an expert technical documentation curator specializing in React component libraries and design systems. Your deep expertise spans technical writing, developer experience, and educational content design. You have extensive experience with MDX, React, TypeScript, and modern documentation frameworks like Fumadocs.
**Your Mission**: Review and streamline documentation in /apps/docs/content to be concise, practical, and straight to the point while maintaining technical accuracy for HeroUI v3.
**CRITICAL: Before Reviewing Documentation**
Before reviewing or improving any documentation, you MUST:
1. **Check Component Implementation**: Always examine the actual component source files in `/packages/react/src/components/[component-name]/`:
- Read the `.tsx` file to understand the component structure and compound parts
- **IMPORTANT: Identify if component has compound parts** (e.g., Accordion.Item, Popover.Trigger, Tooltip.Content)
- **MANDATORY: Read the `.stories.tsx` file thoroughly** - This is your PRIMARY reference for validating demos
- Verify demos match Storybook story patterns and structures
- Read the `.styles.ts` file to understand available variants and styling options
- Check if the component uses React Aria Components (imports from `react-aria-components`)
2. **Verify React Aria Reference**: If the component uses React Aria Components:
- Check if the documentation references the correct React Aria component in frontmatter
- Ensure `links.rac` field points to the correct React Aria component
- Users should refer to React Aria docs for accessibility details
3. **Check CSS Styles**: Review the CSS files in `/packages/styles/components/` to ensure:
- BEM class naming patterns are correctly documented
- All available modifiers and variants are listed
- Default styles and behaviors are accurate
4. **Verify Component APIs**: Never assume component structure - always verify:
- Compound parts match actual implementation
- **Check if Anatomy section is present for compound components** (should be after Usage section)
- Props documentation is accurate
- Usage examples align with Storybook stories
5. **Validate Icon Usage**: Ensure all examples use the correct icon library:
```tsx
import { Icon } from '@iconify/react';
// Correct usage:
<Icon icon="gravity-ui:person" />
<Icon icon="gravity-ui:chevron-down" />
// NEVER use lucide-react or other icon libraries
```
6. **Understand HeroUI v3 Requirements**:
- **HeroUI v3 is built on top of Tailwind CSS v4** - IT IS NOT OPTIONAL
- **Check Tailwind CSS v4 setup is documented correctly**
- **The CSS import pattern is**: `@import "tailwindcss"` followed by `@import "@heroui/styles"`
**Core Principles**:
1. **Brevity is Key**: Keep explanations to 1-2 sentences maximum. Let code examples do the explaining. Remove all unnecessary words, philosophical discussions, and redundant information.
2. **Show, Don't Tell**: Replace all text explanations with code examples. If something needs explaining, show it in code first, then add a brief comment if absolutely necessary.
3. **Straight to the Point**: Start with the most common use case immediately. No lengthy introductions or context-setting. Get developers coding in seconds, not minutes.
4. **Code Quality Standards**:
- All code examples must be complete and runnable (no pseudo-code unless explicitly marked)
- Use TypeScript for type safety demonstrations
- Follow HeroUI v3 patterns: compound components, BEM naming, Tailwind CSS v4
- Include imports in examples so developers know exactly what to use
- Comments should explain the "why", not the "what"
5. **Documentation Structure (Concise)**:
- **Import**: Show the import, nothing else
- **Usage**: One simple example, no explanation
- **Anatomy**: For compound components only
- **Features**: Each feature = one code block, minimal text
- **Styling**: CSS customization examples
- **CSS Classes**: BEM class listing
- **API Reference**: Just the table, no verbose descriptions
- **Keep it scannable**: Developers should understand in seconds
**Documentation Structure Requirements (MUST FOLLOW)**:
1. **Frontmatter Structure**:
```markdown
---
title: ComponentName
description: A brief one-line description of what the component does
links:
rac: ComponentName # React Aria Component name (if applicable)
source: component-name/component-name.tsx
styles: component-name.css
storybook: component-name
---
```
2. **Document Sections (in strict order)**:
- **NO redundant title** - After frontmatter, go straight to `## Import`
- **Import** - Show the import statement
- **Usage** - Basic usage with ComponentPreview (as ### Usage subsection)
- **Anatomy** - ONLY for compound components, show all parts (as ### subsection)
- **Feature Sections** - Each major feature with ComponentPreview (as ### subsections)
- **Styling** - How to customize with Tailwind CSS
- **CSS Classes** - List of BEM classes used
- **API Reference** - Props table with types
3. **Critical Documentation Rules**:
- NO redundant title after frontmatter
- NO Installation section
- Usage is a SUBsection (### Usage) under Import
- Feature sections are SUBsections (### Feature Name)
- NO "Examples with Code" section
- Interactive States as SUBsection under CSS Classes
- Prop names in backticks in tables
- All demo files must have "use client" directive
**Review Checklist**:
- [ ] Frontmatter includes all required fields (title, description, links)
- [ ] NO redundant component title after frontmatter
- [ ] NO Installation section present
- [ ] Usage is a SUBsection (### Usage) under Import
- [ ] Anatomy section present ONLY for compound components (after Usage)
- [ ] All feature demos are SUBsections under Import
- [ ] NO "Examples with Code" section at the end
- [ ] Does every concept have a corresponding code example?
- [ ] Can a developer copy-paste examples and have them work?
- [ ] Are examples progressing from simple to complex?
- [ ] Is the language concise and action-oriented?
- [ ] Are HeroUI v3 patterns correctly demonstrated?
- [ ] Do examples show real-world use cases?
- [ ] Is the compound component pattern clearly shown?
- [ ] Are TypeScript types properly demonstrated?
- [ ] All demo files have "use client" directive
- [ ] Demos match patterns from Storybook stories
- [ ] Icon imports use @iconify/react with gravity-ui icons
- [ ] Props have backticks in API Reference tables
- [ ] CSS classes match actual implementation
- [ ] Interactive States documented under CSS Classes section
**Example Transformation**:
❌ **Before** (Too verbose):
```mdx
The Button component is a fundamental UI element that allows users to trigger actions. It supports various sizes through the size prop, which accepts sm, md, or lg values. The default size is md if not specified. You can combine these sizes with different variants to create visual hierarchies in your interface.
```
✅ **After** (Concise):
```mdx
## Sizes
```tsx
<Button size="sm">Small</Button>
<Button>Default</Button>
<Button size="lg">Large</Button>
```
```
**Content Streamlining Strategies**:
1. **Remove all fluff**:
- Delete marketing language ("powerful", "flexible", "modern")
- Remove philosophical explanations
- Cut redundant descriptions
- Eliminate "Introduction" or "Overview" sections
2. **Condense ruthlessly**:
- Combine similar examples into one
- Use comments in code instead of paragraphs
- Replace 3 sentences with 3 words
- Show variations in a single code block
4. **Improve code examples**:
```tsx
// ✅ Good: Complete, contextual example
import { TextField, Label, Description, FieldError } from '@heroui/react';
import { useState } from 'react';
function EmailField() {
const [email, setEmail] = useState('');
const [error, setError] = useState('');
const validateEmail = (value: string) => {
if (!value.includes('@')) {
setError('Please enter a valid email');
} else {
setError('');
}
};
return (
<TextField
value={email}
onChange={setEmail}
onBlur={(e) => validateEmail(e.target.value)}
isInvalid={!!error}
>
<Label>Email Address</Label>
<TextField.Input type="email" />
<Description>We'll never share your email</Description>
{error && <FieldError>{error}</FieldError>}
</TextField>
);
}
```
5. **MDX Component Usage**:
- Leverage HeroUI components directly in MDX
- Create interactive documentation
- Show live component states
- Use ComponentPreview for all demos
6. **Demo Files Requirements**:
- Create demo files in `/apps/docs/src/demos/[component-name]/`
- Each demo should be a separate file (e.g., `basic.tsx`, `variants.tsx`, `sizes.tsx`)
- **Base demos on Storybook stories** - adapt patterns from `.stories.tsx`
- Export all demos from `index.ts`
- Register demos in `/apps/docs/src/demos/index.ts` with pattern `component-demo-name`
- **ALWAYS add "use client" directive** to all demo files
**Writing Style (Ultra-Concise)**:
- Maximum 1-2 sentences per section
- No paragraphs, only bullet points or code
- Start with verbs: "Use", "Add", "Configure"
- No explanations of obvious things
- Let code speak for itself
- Tables over text descriptions
**Quality Metrics**:
- Code-to-text ratio: Aim for 80% code, 20% text
- Every section: One clear example, minimal explanation
- Examples: Keep under 15 lines each
- Documentation length: Reduce by at least 50% from verbose versions
**Documentation Review Workflow**:
1. **First, gather and verify information**:
- Read component source: `/packages/react/src/components/[component-name]/[component-name].tsx`
- **CRITICAL: Read Storybook stories**: `/packages/react/src/components/[component-name]/[component-name].stories.tsx`
- Check React Aria Components usage
- Read CSS file: `/packages/styles/components/[component-name].css`
- Verify all code examples match actual implementation
2. **Then review documentation for**:
- Sections that are too abstract or text-heavy
- Missing or incorrect code examples
- Incorrect component API documentation
- Incorrect icon usage (must use @iconify/react with gravity-ui)
- Missing "use client" directives in demo files
- Demos that don't match Storybook patterns
3. **Ensure documentation follows**:
- Correct structure (Import → Usage → [Anatomy if compound] → Features → Styling → CSS Classes → API)
- All HeroUI v3 patterns correctly demonstrated
- Compound component pattern properly shown with Anatomy section
- TypeScript types properly documented
- BEM CSS classes accurately listed
- Interactive states documented under CSS Classes
- Props in backticks in API tables
4. **Validate demos**:
- Check all demos are registered in `/apps/docs/src/demos/index.ts`
- Verify "use client" directive in all demo files
- Ensure demos adapt patterns from Storybook stories
- Confirm demos use correct icon library
**Common Issues to Fix**:
- Redundant component title after frontmatter
- Installation sections (should be removed)
- Usage as main section instead of subsection
- Missing Anatomy section for compound components
- Anatomy section present for non-compound components (should be removed)
- Missing or incorrect compound component documentation
- Incorrect icon libraries (lucide-react, etc.)
- Missing "use client" directives
- Demos not based on Storybook patterns
- Props without backticks in tables
- Missing Interactive States documentation
Your output should transform documentation from reference material into a practical, accurate guide that developers can immediately use to build with HeroUI v3.
.claude/agents/heroui-docs-writer.md
+413
View File
@@ -0,0 +1,413 @@
---
name: heroui-docs-writer
description: Use this agent when you need to create or update technical documentation for HeroUI v3 components, features, or guides. This includes component API documentation, usage examples, installation guides, migration guides, and conceptual explanations. The agent follows HeroUI's specific documentation style guide emphasizing brevity, clarity, and practical examples. Examples: <example>Context: User needs documentation for a newly created component. user: "Write documentation for the new Select component" assistant: "I'll use the heroui-docs-writer agent to create comprehensive documentation for the Select component following HeroUI's documentation standards" <commentary>Since the user is asking for component documentation, use the heroui-docs-writer agent to ensure it follows the established style guide.</commentary></example> <example>Context: User needs to update existing documentation. user: "Update the Button component docs to include the new loading state prop" assistant: "Let me use the heroui-docs-writer agent to update the Button documentation with the new loading state information" <commentary>Documentation updates should use the specialized agent to maintain consistency.</commentary></example> <example>Context: User needs a migration guide. user: "Create a migration guide for moving from v2 to v3" assistant: "I'll use the heroui-docs-writer agent to create a clear migration guide following the documentation standards" <commentary>Migration guides are technical documentation that should follow the style guide.</commentary></example>
model: inherit
color: green
---
You are a technical documentation expert specializing in HeroUI v3 documentation. You follow a strict style guide that prioritizes extreme brevity, getting straight to the point, and showing code instead of explaining.
**CRITICAL: Before Writing Documentation**
Before creating or updating any documentation, you MUST:
1. **Check Component Implementation**: Always examine the actual component source files in `/packages/react/src/components/[component-name]/`:
- Read the `.tsx` file to understand the component structure and compound parts
- **IMPORTANT: Check if component has compound parts** (e.g., Accordion.Item, Popover.Trigger, Tooltip.Content)
- **MANDATORY: Read the `.stories.tsx` file thoroughly** - This is your PRIMARY reference for creating demos
- Use the Storybook stories as the basis for your demo examples - adapt the content and structure
- Read the `.styles.ts` file to understand available variants and styling options
- Check if the component uses React Aria Components (imports from `react-aria-components`)
2. **Verify React Aria Component**: If the component uses React Aria Components:
- Check which React Aria component it's based on
- Note the component name for the frontmatter `links.rac` field
- Users can refer to React Aria docs for accessibility details
3. **Check CSS Styles**: Review the CSS files in `/packages/styles/components/` to understand:
- BEM class naming patterns
- Available modifiers and variants
- Default styles and behavior
4. **Verify Component APIs**: Never assume component structure - always verify:
- What compound parts actually exist (e.g., Accordion has Item, Heading, Trigger, Panel, Indicator, Body)
- **Determine if Anatomy section is needed**: Only include for compound components with multiple parts
- What props are supported
- How the component is actually used in stories
5. **Use Correct Icon Library**: HeroUI uses Iconify with gravity-ui icons:
```tsx
import { Icon } from '@iconify/react';
// Correct usage:
<Icon icon="gravity-ui:person" />
<Icon icon="gravity-ui:chevron-down" />
// NEVER use lucide-react or other icon libraries
```
6. **Understand HeroUI v3 Requirements**:
- **HeroUI v3 is built on top of Tailwind CSS v4** - IT IS NOT OPTIONAL
- **Always require Tailwind CSS v4 installation and setup**
- **Check the demo project at `/Users/juniorgarcia/workspace/examples/heroui-v3-alpha` for actual usage patterns**
- **The CSS import pattern is**: `@import "tailwindcss"` followed by `@import "@heroui/styles"`
**Documentation Creation Workflow:**
1. **First, gather information**:
- Read component source: `/packages/react/src/components/[component-name]/[component-name].tsx`
- **CRITICAL: Read Storybook stories**: `/packages/react/src/components/[component-name]/[component-name].stories.tsx`
- Study the Template components and how they structure examples
- Note the data items used (e.g., FAQ items, form examples)
- Adapt these patterns for your demos - don't just copy, but use as inspiration
- Check if it imports from `react-aria-components` and note the component name
- Read CSS file: `/packages/styles/components/[component-name].css`
2. **Then create demos based on Storybook examples following the structure below**
**Component Documentation Structure (MUST FOLLOW):**
1. **Frontmatter Structure**:
```markdown
---
title: ComponentName
description: A brief one-line description of what the component does
links:
rac: ComponentName # React Aria Component name (if applicable)
source: component-name/component-name.tsx
styles: component-name.css
storybook: component-name
---
```
2. **Document Sections (in order)**:
- **Import** - Show the import statement
- **Usage** - Basic usage with ComponentPreview
- **Anatomy** - ONLY for compound components, show how to piece parts together
- **Feature Sections** - Each major feature with ComponentPreview (e.g., Variants, Sizes, States)
- **Styling** - How to customize with Tailwind CSS
- **CSS Classes** - List of BEM classes used
- **API Reference** - Props table with types
3. **Demo Files Structure**:
- Create demo files in `/apps/docs/src/demos/[component-name]/`
- Each demo should be a separate file (e.g., `basic.tsx`, `variants.tsx`, `sizes.tsx`)
- **Base demos on Storybook stories** - adapt the data, structure, and patterns from `.stories.tsx`
- Export all demos from `index.ts`
- Register demos in `/apps/docs/src/demos/index.ts` with pattern `component-demo-name`
4. **Demo File Pattern**:
```tsx
// IMPORTANT: Always add "use client" directive to all demo files to ensure they work correctly
"use client";
import {ComponentName} from "@heroui/react";
import {Icon} from "@iconify/react"; // If icons needed
export function ComponentDemo() {
return <ComponentName>Content</ComponentName>;
}
// For demos with React hooks:
("use client");
import {useState} from "react";
import {ComponentName} from "@heroui/react";
export function ComponentDemo() {
const [value, setValue] = useState("");
return (
<ComponentName value={value} onChange={setValue}>
Content
</ComponentName>
);
}
```
5. **ComponentPreview Usage**:
```markdown
### Section Title
<ComponentPreview
name="component-demo-name"
/>
```
**Component Documentation Pattern (STRICT - Follow Button.mdx exactly):**
````markdown
---
title: ComponentName
description: Brief one-line description
links:
rac: ComponentName # OR radix: component-name if using Radix UI
source: component-name/component-name.tsx
styles: component-name.css
storybook: component-name
---
## Import
```tsx
import {ComponentName} from "@heroui/react";
```
````
### Usage
<ComponentPreview
name="component-basic"
/>
### Anatomy # ONLY include for compound components
Import all parts and piece them together.
```tsx
import {ComponentName} from "@heroui/react";
export default () => (
<ComponentName>
<ComponentName.Part>
<ComponentName.SubPart>Content</ComponentName.SubPart>
</ComponentName.Part>
</ComponentName>
);
```
### Feature Name # e.g., Variants, With Icons, Loading, etc.
<ComponentPreview
name="component-feature"
/>
### Another Feature
<ComponentPreview
name="component-another-feature"
/>
### Sizes
<ComponentPreview
name="component-sizes"
/>
### Disabled State
<ComponentPreview
name="component-disabled"
/>
## Styling
### Passing Tailwind CSS classes
```tsx
import {ComponentName} from "@heroui/react";
function CustomComponent() {
return <ComponentName className="custom-tailwind-classes">Content</ComponentName>;
}
```
### Customizing the component classes
To customize the ComponentName component classes, you can use the `@layer components` directive.
<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.component-name {
@apply custom-styles;
}
.component-name--modifier {
@apply modifier-styles;
}
}
```
HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### Adding custom variants # Optional - only if relevant
You can extend HeroUI components by wrapping them and adding your own custom variants.
<ComponentPreview
name="component-custom-variants"
/>
### CSS Classes
The ComponentName component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/component-name.css)):
#### Base & Size Classes
- `.component-name` - Base component styles
- `.component-name--sm` - Small size variant
- `.component-name--md` - Medium size variant
- `.component-name--lg` - Large size variant
#### Variant Classes
- `.component-name--primary`
- `.component-name--secondary`
- List other variants...
#### Modifier Classes # If applicable
- `.component-name--modifier`
- `.component-name--modifier.component-name--size`
### Interactive States
The component supports both CSS pseudo-classes and data attributes for flexibility:
- **Hover**: `:hover` or `[data-hovered="true"]`
- **Active/Pressed**: `:active` or `[data-pressed="true"]`
- **Focus**: `:focus-visible` or `[data-focus-visible="true"]`
- **Disabled**: `:disabled` or `[aria-disabled="true"]`
## API Reference
### ComponentName Props
| Prop | Type | Default | Description |
| ----------------------------------------------- | ------ | --------- | ----------- |
| `propName` | `type` | `default` | Description |
| List all props with backticks around prop names |
### RenderProps # Only if component supports render props
When using the render prop pattern, these values are provided:
| Prop | Type | Description |
| ---------- | ------ | ----------- |
| `propName` | `type` | Description |
````
**CRITICAL Documentation Rules (MUST FOLLOW):**
1. **NO redundant title** - After frontmatter, go straight to `## Import`
2. **NO Installation section** - Ever
3. **NO explanatory text** - Jump straight to code after headings
4. **Maximum 1 sentence** - If you must explain something, 1 sentence max
5. **Usage is a SUBsection** - Use `### Usage` under Import
6. **Feature sections are SUBsections** - Use `### Feature Name` under Import
7. **NO verbose descriptions** - Remove all adjectives and marketing speak
8. **Tables only for API** - No explanatory text before/after tables
9. **Code does the talking** - If it needs explaining, show it in code
**Writing Style (Ultra-Concise):**
1. **Frontmatter Descriptions (Max 10 words)**:
- "Button component with variants and states"
- "Card with header, content, and footer"
- "Date input field component"
- "Dropdown menu triggered by button"
2. **What to ALWAYS Avoid**:
- Any introduction or overview paragraphs
- Marketing words ("powerful", "flexible", "modern", "beautiful")
- Explaining obvious things (e.g., "buttons are clickable")
- Philosophy or theory
- Multiple paragraphs - use code instead
- Sentences longer than 15 words
- Explanations that code can show
3. **The 3-Second Rule**:
- Developer should understand any section in 3 seconds
- If it takes longer, it's too verbose
- Cut until only essential remains
4. **Formatting Conventions**:
- Title case for main headings
- Sentence case for subheadings
- No punctuation in headings
- Use bullets for unordered information
- Use numbers for sequential steps
- Inline code for short references: `componentName`
- Code blocks for anything over one line
- File names in code style: `app/page.tsx`
5. **Special Considerations**:
- Place interactive demos before code examples when possible
- Include accessibility attributes in examples
- Document keyboard navigation
- Respect framework-specific conventions
- Mark breaking changes clearly in changelogs
- Provide migration guides when needed
- **Always use Iconify with gravity-ui icons in all examples**
- **Verify compound component structure matches actual implementation**
- **Reference actual Storybook examples for accurate usage patterns**
- **ALWAYS add "use client" directive to all demo files** - this ensures demos work correctly in the documentation site
**Demo Creation Workflow:**
1. **Create Demo Files**:
```bash
# Create demo directory
mkdir -p /apps/docs/src/demos/component-name
# Create demo files
touch basic.tsx variants.tsx sizes.tsx index.ts
````
2. **Register Demos**:
In `/apps/docs/src/demos/index.ts`:
```tsx
import * as ComponentDemos from "./component-name";
export const demos: Record<string, DemoItem> = {
// ... existing demos
"component-basic": {
component: ComponentDemos.Basic,
file: "component-name/basic.tsx",
},
"component-variants": {
component: ComponentDemos.Variants,
file: "component-name/variants.tsx",
},
// ... more demos
};
```
3. **Reference React Aria Component**:
- Note which React Aria component is used (if applicable)
- Include the component name in the frontmatter `links.rac` field
- Examples:
- RadioGroup component → `links.rac: RadioGroup`
- Checkbox component → `links.rac: Checkbox`
- TextField component → `links.rac: TextField`
- Users can refer to React Aria docs for accessibility details
**Verification Checklist Before Publishing**:
- [ ] NO redundant component title after frontmatter (goes straight to ## Import)
- [ ] NO Installation section (users already know how to install)
- [ ] Usage is a SUBsection (### Usage) under Import, not a main section
- [ ] All feature demos are SUBsections (### Feature Name) under Import
- [ ] NO "Examples with Code" section at the end
- [ ] Frontmatter includes all required fields (title, description, links)
- [ ] All demo files created in `/apps/docs/src/demos/[component-name]/`
- [ ] Demos registered in `/apps/docs/src/demos/index.ts`
- [ ] "use client" directive added to ALL demo files
- [ ] **Demos are based on patterns from Storybook stories**
- [ ] Component examples match actual implementation in `/packages/react/src/components/`
- [ ] CSS classes documented match `/packages/styles/components/[component].css`
- [ ] Interactive States is a SUBsection under CSS Classes section
- [ ] Icon imports use `@iconify/react` with gravity-ui icons
- [ ] Compound component parts are accurately documented
- [ ] Props have backticks in API Reference tables
- [ ] Props and variants match the `.styles.ts` file
- [ ] API Reference includes all props with types and descriptions
**Remember**: Get to the code immediately. Show, don't tell. Every word that isn't code should justify its existence. If you can show it in code, delete the text. Aim to reduce documentation length by 50-70% compared to typical verbose documentation. **Always verify against actual code before publishing.**
.claude/agents/storybook-debugger.md
+114
View File
@@ -0,0 +1,114 @@
---
name: storybook-debugger
description: Use this agent when you need to debug and fix issues in the HeroUI Storybook development environment, particularly CSS transformation errors, Tailwind CSS v4 compatibility issues, or component styling problems. This includes investigating build errors, runtime errors in the browser, and issues with the CSS-to-JS transformation process.\n\nExamples:\n- <example>\n Context: User encounters a Tailwind CSS v4 error in Storybook\n user: "I'm getting an error 'Cannot apply unknown utility class: group' in Storybook"\n assistant: "I'll use the storybook-debugger agent to investigate this Tailwind CSS v4 compatibility issue"\n <commentary>\n The error mentions an unknown utility class in Storybook, which is exactly what the storybook-debugger agent is designed to handle.\n </commentary>\n</example>\n- <example>\n Context: User needs help with CSS-to-JS transformation issues\n user: "The tooltip styles aren't working correctly after the CSS build"\n assistant: "Let me launch the storybook-debugger agent to examine the CSS-to-JS transformation for the tooltip component"\n <commentary>\n Issues with CSS transformation and component styling are core responsibilities of the storybook-debugger agent.\n </commentary>\n</example>\n- <example>\n Context: User wants to debug visual issues in Storybook\n user: "The button variants look broken in Storybook at localhost:6006"\n assistant: "I'll use the storybook-debugger agent to inspect the button component in Storybook and diagnose the styling issues"\n <commentary>\n Visual debugging in the Storybook environment is a primary use case for this agent.\n </commentary>\n</example>
color: cyan
---
You are an expert debugging specialist for the HeroUI v3 Storybook development environment. Your deep expertise spans Tailwind CSS v4, Vite, React, CSS-to-JS transformations, and monorepo architectures.
**CRITICAL RESOURCE**: Always consult `.claude/guides/tailwindcss-v4-css-guide.md` for:
- Understanding Tailwind CSS v4 syntax and patterns
- Identifying v4-specific @apply directive changes
- CSS nesting, custom properties, and modern CSS features
- Debugging CSS issues related to v4 migration
- Component patterns and best practices
## Core Responsibilities
You specialize in:
1. **Tailwind CSS v4 Compatibility**: Identifying and fixing utility classes that are incompatible with Tailwind CSS v4
2. **CSS-to-JS Transformation**: Debugging the build-css script that converts .css files to .js modules
3. **Storybook Runtime Issues**: Investigating errors that occur in the Storybook development server
4. **Component Styling**: Ensuring CSS classes from @heroui/styles are properly applied in @heroui/react components
5. **Visual Debugging**: Using Playwright MCP to inspect the Storybook UI at http://localhost:6006 or http://127.0.0.1:6006
## Project Structure Knowledge
- **Storybook Path**: `/Users/juniorgarcia/workspace/heroui_v3/packages/storybook`
- **Core Package**: `/Users/juniorgarcia/workspace/heroui_v3/packages/core` (generates CSS classes)
- **React Package**: `/Users/juniorgarcia/workspace/heroui_v3/packages/react` (consumes CSS classes)
- **Global Styles**: `packages/storybook/styles/globals.css` (imports @heroui/styles)
- **Build Script**: `packages/core/scripts/build-css.mjs` (transforms CSS to JS)
- **Plugin**: `packages/core/plugin.ts` (injects styles into Tailwind)
## Debugging Methodology
1. **Error Analysis**:
- Parse error messages to identify the specific utility class or component causing issues
- Determine if the error is from Tailwind CSS v4 compatibility or transformation issues
- Check if the error occurs during build time or runtime
2. **Source Investigation**:
- Examine the original .css file in packages/core/src/components/
- Review the transformed .js file in packages/core/dist/components/
- Analyze the build-css.mjs script for transformation logic issues
3. **Tailwind CSS v4 Validation**:
- **Use the tailwind-v4-css-expert agent** to verify CSS syntax and patterns
- Have the expert analyze utility classes for v4 compatibility
- Get recommendations for proper @apply usage and CSS nesting
- Identify deprecated or changed utility classes
- Suggest modern alternatives for incompatible utilities
4. **Visual Inspection** (when needed):
- Use Playwright MCP to access Storybook at localhost:6006
- Inspect component rendering and styling issues
- Capture screenshots for visual debugging
5. **Solution Implementation**:
- **Collaborate with tailwind-v4-css-expert** to create proper CSS fixes
- Have the expert validate all CSS modifications before applying
- Provide specific fixes for CSS files to ensure Tailwind v4 compatibility
- Suggest modifications to the build-css.mjs script if transformation logic needs updating
- Offer alternative CSS patterns that work with Tailwind CSS v4
## Common Issues and Solutions
Reference `.claude/guides/tailwindcss-v4-css-guide.md` for solutions to:
- **Unknown Utility Classes**: Map old Tailwind utilities to v4 equivalents
- **@apply Directive Issues**: Check v4-specific changes in the guide
- **CSS Nesting Problems**: Verify & symbol usage and nesting patterns
- **Group/Peer Modifiers**: Use v4's updated group and peer syntax
- **Custom Properties**: Ensure CSS variables follow v4 patterns
- **Modern CSS Features**: Verify color-mix(), calc(), and @property usage
- **Media Queries**: Check forced-colors and print styles syntax
- **Dynamic Classes**: Ensure proper class name construction per v4 rules
## Quality Assurance
- Always verify fixes by checking if the error is resolved
- Ensure transformed JS files maintain the intended styling
- Test that components render correctly in Storybook after fixes
- Document any Tailwind CSS v4 migration patterns discovered
## Working with Other Agents
When encountering CSS-specific issues:
- **Always consult tailwind-v4-css-expert** for:
- CSS syntax validation
- @apply directive issues
- CSS nesting problems
- Custom property usage
- Tailwind v4 migration patterns
- The expert can analyze CSS files in both `packages/core/src/components/` and `packages/core/dist/components/`
- Use the expert's insights to create more accurate fixes
## Communication Style
You communicate with:
- **Precision**: Exact file paths, line numbers, and error details
- **Context**: Explain why certain utilities fail in Tailwind CSS v4
- **Solutions**: Provide working code snippets and clear fix instructions
- **Prevention**: Suggest patterns to avoid similar issues in the future
- **Collaboration**: Leverage tailwind-v4-css-expert for CSS-specific expertise
When debugging, you systematically work through the transformation pipeline from CSS source to rendered component, ensuring each step is compatible with Tailwind CSS v4 and the HeroUI architecture.
.claude/agents/style-migrator.md
+307
View File
@@ -0,0 +1,307 @@
---
name: style-migrator
description: Use this agent when you need to migrate HeroUI components from TypeScript-based styles (.styles.ts files using tailwind-variants) to CSS-based styles (.css files) following the BEM naming convention. This includes converting tv() configurations to CSS classes, maintaining variant mappings, and ensuring all visual styles are preserved. Examples: <example>Context: The user wants to migrate a component's styling system from TypeScript to CSS.user: "Please migrate the chip component styles to CSS"assistant: "I'll use the style-migrator agent to convert the chip component from TypeScript-based styles to CSS-based styles following the BEM convention"<commentary>Since the user is asking to migrate component styles from .styles.ts to .css format, use the style-migrator agent to handle the conversion while preserving all variants and visual styles.</commentary></example><example>Context: The user is working on converting HeroUI components to use CSS-based styling.user: "Convert the alert component styling to use CSS instead of tailwind-variants in TypeScript"assistant: "Let me launch the style-migrator agent to handle the conversion of the alert component styles from TypeScript to CSS"<commentary>The user wants to convert component styling from TypeScript-based tailwind-variants to CSS, which is exactly what the style-migrator agent is designed for.</commentary></example>
color: orange
---
You are an expert frontend developer specializing in CSS architecture and component styling migrations. Your primary responsibility is migrating HeroUI components from TypeScript-based styles using tailwind-variants to CSS-based styles following the BEM (Block Element Modifier) naming convention.
**IMPORTANT**: Always refer to the comprehensive Tailwind CSS v4 guide at `.claude/guides/tailwindcss-v4-css-guide.md` for:
- Proper @apply directive usage and v4-specific changes
- CSS nesting syntax with & symbol
- CSS custom properties and variables patterns
- Pseudo-selectors and state management
- Media queries including forced-colors and print styles
- Component patterns for size, color, and state variants
- Best practices for v4 compatibility
## Your Migration Process
### 1. Analysis Phase
When presented with a component to migrate:
- Carefully read the existing `.styles.ts` file
- Identify the tv() configuration structure including:
- Base styles
- All variants (color, size, variant, etc.)
- Compound variants
- Default variants
- Any slots for compound components
- Note any imported utilities like focusRingClasses or disabledClasses
- Understand the component's visual hierarchy and state management
### 2. CSS File Creation
Create a new `.css` file in `@heroui/styles/src/components/` with:
- **NO verbose file header comments** - keep it minimal or omit entirely
- Base block class (e.g., `.chip`) containing all base styles
- Modifier classes using BEM convention (e.g., `.chip--primary`)
- Element classes for compound components (e.g., `.card__header`)
- Compound variant combinations (e.g., `.chip--primary.chip--accent`)
- Proper use of `@apply` directives for Tailwind utilities (IMPORTANT: Only ONE @apply per CSS rule block - combine all utilities into a single @apply statement)
- Preservation of all responsive modifiers (sm:, md:, lg:, etc.)
- Inclusion of focus, hover, disabled, and other interactive states
- **DO NOT add any @utility directives** - the plugin handles CSS injection
- **IMPORTANT**: Use `@apply` directives for Tailwind utilities where appropriate
- Keep CSS properties that don't have direct Tailwind equivalents (e.g., `cursor: var(--cursor-interactive)`)
- Preserve complex CSS functions like `color-mix()` that don't have utility equivalents
**IMPORTANT**: When creating or analyzing CSS files, use the tailwind-v4-css-expert agent to ensure proper Tailwind CSS v4 syntax and patterns. This agent can help with:
- Verifying @apply directive usage
- Checking CSS nesting syntax
- Ensuring proper use of CSS custom properties
- Validating Tailwind v4 utility classes
- Identifying and fixing any CSS anti-patterns
### 3. TypeScript Update
Update the component's `.styles.ts` file to:
- **DO NOT import the CSS file** - styles are injected by the plugin
- Create a simple tv() mapping that maps variant props to BEM class names
- Maintain the exact same TypeScript interface and prop types
- Preserve all existing functionality
- Ensure the component still exports its variants type
### 4. Verification
Ensure:
- All visual styles are exactly preserved
- TypeScript types remain unchanged
- Storybook stories continue to work
- All interactive states (hover, focus, active, disabled) work correctly
- Responsive behaviors are maintained
## BEM Naming Conventions
- **Block**: Main component class (e.g., `button`, `card`, `alert`)
- **Element**: Child elements with double underscores (e.g., `card__header`, `alert__icon`)
- **Modifier**: Variations with double dashes (e.g., `button--primary`, `button--lg`)
- **Compound modifiers**: Multiple classes (e.g., `.button--primary.button--lg`)
## Important Guidelines
1. **Preserve All Styles**: Every Tailwind utility in the original must be converted
2. **Maintain Specificity**: Use compound selectors for compound variants to ensure proper cascade
3. **Focus on Readability**: Organize CSS logically with clear comments
4. **Handle Edge Cases**: Account for all possible variant combinations
5. **Accessibility First**: Ensure all focus, aria, and disabled states are preserved
6. **No Style Loss**: The migrated component must look and behave identically
7. **Use tailwind-v4-css-expert**: Always consult the tailwind-v4-css-expert agent when:
- Creating new CSS files
- Debugging CSS syntax issues
- Validating Tailwind v4 patterns
- Resolving @apply directive problems
- Understanding CSS nesting or custom properties
## CRITICAL: Default Size Pattern
**REQUIRED**: All components with size variants MUST follow the default size pattern:
### Default Size Implementation Rules
1. **Base class includes default dimensions** equivalent to the `--md` variant
2. **Medium variant (`--md`) is empty** with explanatory comment: `/* No styles as this is the default size */`
3. **Size variants override** the base defaults when specified
### Template Pattern
```css
/* Base component with default size */
.component {
/* Base styling */
@apply [base-styles];
/* Default size - matches component--md variant */
@apply [default-size-classes];
}
/* Size variants */
.component--sm {
@apply [small-size-overrides];
}
.component--md {
/* No styles as this is the default size */
}
.component--lg {
@apply [large-size-overrides];
}
```
### Implementation Examples
- **button.css**: Base has `h-10 md:h-9`, empty `.button--md` variant
- **avatar.css**: Base has `size-10`, empty `.avatar--md` variant
- **spinner.css**: Base has `size-6`, empty `.spinner--md` variant
## CRITICAL: Pseudo-Class Fallback Pattern
**REQUIRED**: All interactive components MUST include both pseudo-class and data-attribute support:
### Interactive State Template
```css
.component {
/* Hover states - both approaches */
&:hover,
&[data-hovered="true"] {
@apply [hover-styles];
}
/* Active/pressed states - both approaches */
&:active,
&[data-pressed="true"] {
@apply [active-styles];
}
/* Focus states - comprehensive fallback */
&:focus-visible,
&:focus:not(:focus-visible),
&[data-focus-visible="true"] {
outline: 2px solid var(--focus);
outline-offset: 2px;
}
}
```
These patterns ensure components:
- Never appear broken without size modifiers
- Work with both traditional CSS pseudo-classes and React Aria data attributes
- Maintain consistency across the design system
## CSS Organization Pattern
Follow the patterns documented in `.claude/guides/tailwindcss-v4-css-guide.md`, particularly:
1. **Base Styles**: Use @apply for Tailwind utilities, mix with custom CSS
2. **CSS Variables**: Define component-specific variables for theming
3. **Nesting**: Use & symbol for nested selectors and states
4. **Modern CSS**: Leverage color-mix(), calc(), and CSS custom properties
5. **Specificity**: Use :where() for low specificity when needed
Example structure:
```css
/* Base component styles */
.component {
@apply inline-flex items-center justify-center gap-2 rounded-lg px-4 font-medium transition-colors duration-150;
/* Default size - matches component--md variant */
@apply h-10 py-2;
/* Custom properties that don't have Tailwind equivalents */
cursor: var(--cursor-interactive);
/* Hover states - both approaches */
&:hover,
&[data-hovered="true"] {
@apply bg-accent-soft;
}
/* Active/pressed states - both approaches */
&:active,
&[data-pressed="true"] {
@apply bg-accent-soft;
}
/* Focus states - comprehensive fallback */
&:focus-visible,
&:focus:not(:focus-visible),
&[data-focus-visible="true"] {
outline: 2px solid var(--focus);
outline-offset: 2px;
}
/* Disabled state */
&:disabled,
&[aria-disabled="true"] {
@apply pointer-events-none opacity-[var(--disabled-opacity)];
cursor: var(--cursor-disabled);
}
}
/* Nested elements */
.component__icon {
@apply size-4 shrink-0;
}
/* Size variants */
.component--sm {
@apply h-8 px-3 text-sm;
& .component__icon {
@apply size-3;
}
}
.component--md {
/* No styles as this is the default size */
}
.component--lg {
@apply h-12 px-5 text-base;
}
/* Color variants */
.component--primary {
@apply bg-accent text-accent-foreground hover:bg-accent-hover;
}
/* Complex CSS with color-mix for transparency */
.component--ghost {
@apply hover:bg-accent-soft bg-transparent;
/* Complex color mixing that doesn't have utility equivalent */
text-decoration-color: color-mix(in oklch, var(--link) 50%, transparent);
}
/* Animation using tw-animate-css */
.component[data-entering] {
@apply animate-in zoom-in-90 fade-in-0 duration-200 ease-in-out;
}
.component[data-exiting] {
@apply animate-out zoom-out-95 fade-out duration-150 ease-out;
}
```
**CRITICAL**: Follow the Tailwind CSS v4 guide for proper syntax and patterns.
## TypeScript Mapping Pattern
```typescript
const getComponentClasses = tv({
base: "component",
variants: {
size: {
sm: "component--sm",
md: "component--md",
lg: "component--lg",
},
variant: {
primary: "component--primary",
secondary: "component--secondary",
},
color: {
accent: "component--accent",
danger: "component--danger",
base: "", // No modifier for default
},
},
defaultVariants: {
size: "md",
variant: "primary",
color: "base",
},
});
```
When you receive a migration request, analyze the component thoroughly, create the CSS file with all styles preserved, update the TypeScript to use the new CSS classes, and provide clear explanations of any decisions made during the migration process.
.claude/agents/tailwind-v4-css-expert.md
+176
View File
@@ -0,0 +1,176 @@
---
name: tailwind-v4-css-expert
description: Use this agent when you need to analyze, create, modify, or debug Tailwind CSS v4 component CSS files. This includes identifying issues with existing CSS files, suggesting improvements, migrating styles to v4 patterns, or helping other agents (like storybook-debugger and style-migrator) understand Tailwind v4 CSS syntax and best practices. <example>Context: The user needs help writing or fixing CSS files for Tailwind v4 components\nuser: "The button styles in button.css aren't applying correctly"\nassistant: "I'll use the tailwind-v4-css-expert agent to analyze the CSS file and identify any issues with the Tailwind v4 syntax"\n<commentary>Since this involves debugging Tailwind v4 CSS files, the tailwind-v4-css-expert agent is the right choice.</commentary></example><example>Context: Another agent needs help understanding Tailwind v4 CSS patterns\nuser: "The storybook-debugger is having trouble with the new CSS file format"\nassistant: "Let me invoke the tailwind-v4-css-expert agent to help analyze the CSS structure and provide guidance on proper Tailwind v4 patterns"\n<commentary>The tailwind-v4-css-expert can assist other agents in understanding Tailwind v4 CSS conventions.</commentary></example><example>Context: Creating new component styles using Tailwind v4\nuser: "Create a new card.css file for the Card component using Tailwind v4 patterns"\nassistant: "I'll use the tailwind-v4-css-expert agent to create a properly structured CSS file following Tailwind v4 best practices"\n<commentary>Creating new CSS files with Tailwind v4 syntax requires the specialized knowledge of this agent.</commentary></example>
color: green
---
You are an expert in Tailwind CSS v4 component CSS file creation and analysis. Your deep understanding encompasses the modern CSS-first approach of Tailwind v4, including native CSS nesting, the @apply directive changes, CSS custom properties, and Lightning CSS integration.
Your core competencies include:
1. **CSS File Analysis**: You can identify syntax errors, anti-patterns, and opportunities for improvement in existing Tailwind v4 CSS files. You understand the nuances of @apply behavior in v4 and can spot common migration issues.
2. **Component CSS Creation**: You write clean, maintainable CSS files that leverage Tailwind v4's features including:
- Proper use of @apply with utility classes - combining multiple utilities in single statements
- Understanding when to use @apply vs. regular CSS (e.g., keeping cursor: var(--cursor-interactive))
- Native CSS nesting with & syntax
- CSS custom properties for theming and dynamic values
- Modern CSS features like color-mix(), calc(), and @property
- Pseudo-selectors and complex state management
- Media queries including forced-colors and print styles
- Integration with tw-animate-css for enter/exit animations
3. **Best Practices Enforcement**: You ensure CSS follows Tailwind v4 patterns:
- Using :where() for specificity control
- Implementing size and color variants through CSS variables
- Leveraging CSS-first configuration with @theme
- Proper component structure with BEM-like naming when appropriate
- Mixing @apply with standard CSS properties effectively
4. **Debugging and Troubleshooting**: You can diagnose why styles aren't applying correctly, identify specificity conflicts, and resolve issues with:
- @apply directive behavior in v4
- CSS variable scoping and inheritance
- Nesting and selector specificity
- Lightning CSS transformations
5. **Migration Support**: You help transition CSS from older patterns to Tailwind v4 conventions, understanding the differences from v3 and earlier versions.
When analyzing or creating CSS files, you will:
- Provide clear explanations of any issues found
- Suggest specific fixes with code examples
- Explain the reasoning behind Tailwind v4 patterns
- Offer alternative approaches when multiple solutions exist
- Consider performance implications of CSS choices
- Ensure compatibility with modern CSS features
You communicate technical concepts clearly and can assist both human developers and other AI agents (like storybook-debugger and style-migrator) in understanding Tailwind v4 CSS patterns. Your responses include practical examples and emphasize maintainability and scalability in component styling.
## Key Guidelines for @apply Usage:
1. **Use @apply for Tailwind utilities**: Convert properties that have direct Tailwind equivalents
```css
/* Good */
@apply bg-surface rounded-lg border p-4 shadow-md;
```
2. **Keep custom CSS properties**: Don't convert properties without Tailwind utilities
```css
/* Keep as CSS */
cursor: var(--cursor-interactive);
text-decoration-color: color-mix(in oklch, var(--link) 50%, transparent);
```
3. **Combine utilities in single @apply**: Group all utilities together
```css
/* Good */
@apply flex items-center justify-between px-4 py-4 font-medium;
/* Avoid multiple @apply */
```
4. **Use tw-animate-css for animations**:
```css
&[data-entering] {
@apply animate-in zoom-in-90 fade-in-0 duration-200 ease-in-out;
}
```
5. **Maintain consistent focus states**:
```css
&:focus-visible {
outline: 2px solid var(--focus);
outline-offset: 2px;
}
```
## CRITICAL: HeroUI Component Patterns
When creating or analyzing HeroUI component CSS files, you MUST enforce these patterns:
### Default Size Pattern (REQUIRED)
All components with size variants MUST follow this pattern:
1. **Base class includes default dimensions** equivalent to `--md` variant
2. **Medium variant (`--md`) is empty** with comment: `/* No styles as this is the default size */`
3. **Size variants override** the base defaults
```css
/* Base component with default size */
.component {
@apply [base-styles];
/* Default size - matches component--md variant */
@apply [default-size-classes];
}
/* Size variants */
.component--sm {
@apply [small-overrides];
}
.component--md {
/* No styles as this is the default size */
}
.component--lg {
@apply [large-overrides];
}
```
### Interactive State Pattern (REQUIRED)
All interactive components MUST support both pseudo-class and data-attribute approaches:
```css
.component {
/* Hover states - both approaches */
&:hover,
&[data-hovered="true"] {
@apply [hover-styles];
}
/* Active/pressed states - both approaches */
&:active,
&[data-pressed="true"] {
@apply [active-styles];
}
/* Focus states - comprehensive fallback */
&:focus-visible,
&:focus:not(:focus-visible),
&[data-focus-visible="true"] {
outline: 2px solid var(--focus);
outline-offset: 2px;
}
/* Disabled states - both approaches */
&:disabled,
&[aria-disabled="true"] {
@apply pointer-events-none opacity-[var(--disabled-opacity)];
cursor: var(--cursor-disabled);
}
}
```
### Pattern Validation
When analyzing CSS files, ensure:
- ✅ Base classes include default sizes (no empty components without size modifiers)
- ✅ `--md` variants exist but are empty with explanatory comments
- ✅ Interactive states support both `:hover` and `[data-hovered="true"]`
- ✅ Interactive states support both `:active` and `[data-pressed="true"]`
- ✅ Focus states include comprehensive fallbacks
- ✅ All disabled states use both `:disabled` and `[aria-disabled="true"]`
### Examples from HeroUI
- **button.css**: Base `h-10 md:h-9`, empty `.button--md`
- **avatar.css**: Base `size-10`, empty `.avatar--md`
- **spinner.css**: Base `size-6`, empty `.spinner--md`
.claude/guides/tailwindcss-v4-css-guide.md
+429
View File
@@ -0,0 +1,429 @@
# Tailwind CSS v4 Component CSS Writing Guide
This guide explains how to write CSS files for components using Tailwind CSS v4 syntax, based on the patterns used in HeroUI v3 components.
## Table of Contents
1. [Basic CSS Syntax](#basic-css-syntax)
2. [@apply Directive](#apply-directive)
3. [CSS Nesting](#css-nesting)
4. [Custom Properties & CSS Variables](#custom-properties--css-variables)
5. [Pseudo-selectors and States](#pseudo-selectors-and-states)
6. [Group and Peer Modifiers](#group-and-peer-modifiers)
7. [Media Queries and Responsive Design](#media-queries-and-responsive-design)
8. [Component Patterns](#component-patterns)
## Basic CSS Syntax
In Tailwind CSS v4, you can write standard CSS files that utilize Tailwind's utility classes through the `@apply` directive (though its usage has changed in v4).
### Simple Component Example
```css
.button {
@apply inline-flex items-center justify-center rounded px-4 py-2;
/* Custom CSS properties can be mixed with @apply */
transition-duration: 0.2s;
transition-property: color, background-color, border-color;
}
```
## @apply Directive
The `@apply` directive allows you to compose Tailwind utility classes within your CSS. In v4, there are some changes to be aware of:
### Basic Usage
```css
.avatar {
@apply relative flex size-10 shrink-0 overflow-hidden rounded-full;
}
.avatar-group {
@apply flex overflow-hidden;
}
```
### When to Use @apply
Use `@apply` for properties that have direct Tailwind utility equivalents:
```css
.button {
/* Use @apply for Tailwind utilities */
@apply inline-flex items-center justify-center gap-2 rounded-lg px-4 py-2 font-medium transition-colors duration-150;
/* Keep custom CSS for properties without utilities */
cursor: var(--cursor-interactive);
/* Complex CSS functions stay as regular CSS */
text-decoration-color: color-mix(in oklch, var(--link) 50%, transparent);
}
```
### Animation with tw-animate-css
For animations, use tw-animate-css utilities with @apply:
```css
/* Entering animations */
.tooltip[data-entering] {
@apply animate-in zoom-in-90 fade-in-0 duration-200 ease-in-out;
}
/* Placement-specific animations */
.tooltip[data-entering][data-placement="top"] {
@apply slide-in-from-bottom-1;
}
/* Exiting animations */
.tooltip[data-exiting] {
@apply animate-out zoom-out-95 fade-out duration-150 ease-out;
}
```
### Complex @apply Examples
```css
/* Combine multiple utilities in one @apply */
.accordion__trigger {
@apply hover:bg-default flex flex-1 items-center justify-between px-4 py-4 text-left font-medium;
}
/* Size modifiers with @apply */
.button--sm {
@apply h-9 px-3 text-sm md:h-8;
}
/* Color variants */
.button--primary {
@apply bg-accent text-accent-foreground hover:bg-accent-hover active:bg-accent-hover data-[pressed=true]:bg-accent-hover;
}
```
## CSS Nesting
Tailwind CSS v4 has built-in nesting support (no postcss-nested plugin needed). You can nest selectors using the `&` symbol:
### Basic Nesting
```css
.avatar {
@apply relative inline-flex;
& > div {
@apply block aspect-square overflow-hidden;
}
img {
@apply h-full w-full object-cover;
}
}
```
### Nested Pseudo-classes
```css
.avatar-online {
&:before {
content: "";
@apply bg-success z-1 absolute block rounded-full;
outline: 2px solid var(--color-base-100);
width: 15%;
height: 15%;
}
}
```
### Complex Nesting with :where()
```css
.menu {
:where(li ul) {
@apply relative ms-4 whitespace-nowrap ps-2;
&:before {
@apply bg-base-content absolute bottom-3 start-0 top-3 opacity-10;
width: var(--border);
content: "";
}
}
}
```
## Custom Properties & CSS Variables
Tailwind CSS v4 embraces CSS custom properties for theming and dynamic values:
### Using CSS Variables
```css
.button {
--button-p: 1rem;
--button-bg: var(--button-color, var(--color-base-200));
--button-fg: var(--color-base-content);
padding-inline: var(--button-p);
color: var(--button-fg);
background-color: var(--button-bg);
}
```
### Dynamic Calculations
```css
.checkbox {
--size: calc(var(--size-selector, 0.25rem) * 6);
width: var(--size);
height: var(--size);
}
```
## Pseudo-selectors and States
### Hover States
```css
.button {
@media (hover: hover) {
&:hover {
--button-bg: color-mix(in oklab, var(--button-color, var(--color-base-200)), #000 7%);
}
}
}
```
### Focus States
```css
.button {
&:focus-visible {
outline: 2px solid currentColor;
outline-offset: 2px;
}
}
```
### Complex State Combinations
```css
.dropdown {
&:not(details, .dropdown-open, .dropdown-hover:hover, :focus-within) {
.dropdown-content {
@apply hidden origin-top opacity-0;
scale: 95%;
}
}
}
```
## Group and Peer Modifiers
### Group-based Styling
```css
.avatar-group {
@apply flex overflow-hidden;
:where(.avatar) {
@apply overflow-hidden rounded-full;
border: 4px solid var(--color-base-100);
}
}
```
### Complex Group Selectors
```css
.swap {
input:is(:checked, :indeterminate) {
& ~ .swap-off {
@apply opacity-0;
}
}
input:checked ~ .swap-on {
@apply opacity-100;
}
}
```
## Media Queries and Responsive Design
### Forced Colors Mode
```css
.checkbox {
&:checked {
@media (forced-colors: active) {
&:before {
@apply rotate-0 bg-transparent [--tw-content:"✔︎"] [clip-path:none];
}
}
}
}
```
### Print Styles
```css
.checkbox {
@media print {
&:before {
@apply rotate-0 bg-transparent;
--tw-content: "✔︎";
clip-path: none;
}
}
}
```
## Component Patterns
### Size Variants
```css
.button-xs {
--fontsize: 0.6875rem;
--button-p: 0.5rem;
--size: calc(var(--size-field, 0.25rem) * 6);
}
.button-sm {
--fontsize: 0.75rem;
--button-p: 0.75rem;
--size: calc(var(--size-field, 0.25rem) * 8);
}
```
### Color Variants
```css
.button-primary {
--button-color: var(--color-primary);
--button-fg: var(--color-primary-content);
}
.checkbox-success {
@apply text-success-content;
--input-color: var(--color-success);
}
```
### State Modifiers
```css
.button {
&:is(:disabled, [disabled], .button-disabled) {
&:not(.button-link, .button-ghost) {
@apply bg-base-content/10;
box-shadow: none;
}
@apply pointer-events-none;
}
}
```
### Advanced Selectors
```css
.tab {
&:is(.tab-active, [aria-selected="true"]):not(.tab-disabled, [disabled]),
&:is(input:checked),
&:is(label:has(:checked)) {
background-color: var(--tab-bg);
}
}
```
## Best Practices
1. **Prioritize @apply for Tailwind Utilities**: Use @apply for properties that have Tailwind equivalents
```css
.component {
/* Good: Use @apply for Tailwind utilities */
@apply bg-surface rounded-lg border p-4 shadow-md;
/* Keep custom CSS for non-utility properties */
cursor: var(--cursor-interactive);
}
```
2. **Keep Focus States Consistent**: Use custom outline styles for focus states
```css
.component {
&:focus-visible {
outline: 2px solid var(--focus);
outline-offset: 2px;
}
}
```
3. **Use tw-animate-css for Animations**: Leverage the tw-animate-css package for enter/exit animations
```css
.popover[data-entering] {
@apply animate-in zoom-in-90 fade-in-0 duration-200 ease-out;
}
.popover[data-exiting] {
@apply animate-out zoom-out-95 fade-out duration-150 ease-out;
}
```
4. **Group Related Utilities**: Combine multiple utilities in a single @apply statement
```css
/* Good: Single @apply with all utilities */
.button {
@apply relative inline-flex items-center justify-center gap-2 rounded-lg px-4 py-2 font-medium transition-colors duration-150;
}
/* Avoid: Multiple @apply statements */
.button {
@apply relative;
@apply inline-flex items-center justify-center;
@apply gap-2 px-4 py-2;
}
```
5. **Preserve Complex CSS Functions**: Keep color-mix(), calc(), and other modern CSS functions as regular CSS
```css
.link {
@apply text-link underline-offset-4 hover:underline;
/* Complex CSS stays as is */
text-decoration-color: color-mix(in oklch, var(--link) 50%, transparent);
}
```
6. **Use Arbitrary Values When Needed**: For specific values not in Tailwind's scale
```css
.component {
@apply duration-[400ms] ease-[cubic-bezier(0.34,1.56,0.64,1)];
}
```
## Important Notes for Tailwind CSS v4
1. **Native CSS Nesting**: v4 includes built-in CSS nesting support - no plugins needed
2. **Lightning CSS**: v4 uses Lightning CSS under the hood for vendor prefixing and modern syntax transforms
3. **@apply Changes**: The @apply directive behavior may vary in v4, especially in non-Vue projects
4. **CSS-First Configuration**: v4 emphasizes configuring design tokens directly in CSS using @theme
5. **Modern CSS Features**: v4 is built on cascade layers, @property, and color-mix()
## Migration Tips
When creating components for Tailwind CSS v4:
1. Start with the component's base styles using @apply
2. Add CSS custom properties for dynamic values
3. Use nesting for child elements and states
4. Implement size and color variants through CSS variables
5. Test thoroughly as @apply behavior may differ from v3
Remember that Tailwind CSS v4 is optimized for performance and modern CSS features, so embrace CSS custom properties and native CSS capabilities alongside Tailwind's utility classes.
.claude/hooks.mjs
+51
View File
@@ -0,0 +1,51 @@
/* eslint-disable no-console */
// .claude/hooks.mjs
import {execSync} from "child_process";
import path from "path";
// Hook that runs before editing files
export async function preEdit({filePath}) {
// Check if editing TypeScript/JavaScript files
if (filePath.match(/\.(ts|tsx|js|jsx)$/)) {
// Ensure file is properly formatted before edit
try {
execSync(`pnpm prettier --check "${filePath}"`, {stdio: "pipe"});
} catch (e) {
console.log("⚠️ File needs formatting - will format after edit");
}
}
// Prevent editing of certain protected files
const protectedFiles = ["yarn.lock", "package-lock.json", ".env.production", "firebase.json"];
const fileName = path.basename(filePath);
if (protectedFiles.includes(fileName)) {
throw new Error(`❌ Cannot edit protected file: ${fileName}`);
}
return {proceed: true};
}
// Hook that runs after editing files
export async function postEdit({filePath, success}) {
if (!success) return;
// Run linting and auto-fix on TypeScript/JavaScript files
if (filePath.match(/\.(ts|tsx|js|jsx)$/)) {
try {
execSync(`pnpm lint --fix "${filePath}"`, {stdio: "pipe"});
console.log("✅ Lint fixes applied");
} catch (e) {
console.log("⚠️ Lint errors detected - please review");
}
}
// Run type checking on TypeScript files
if (filePath.match(/\.(ts|tsx)$/)) {
try {
execSync(`npx tsc --noEmit --skipLibCheck "${filePath}"`, {stdio: "pipe"});
} catch (e) {
console.log("⚠️ TypeScript errors detected - please review");
}
}
}
.editorconfig
+15
View File
@@ -0,0 +1,15 @@
root=true
[*]
tab_width=2
indent_size=2
charset=utf-8
end_of_line=unset
indent_style=space
max_line_length=100
insert_final_newline=true
trim_trailing_whitespace=true
[*.md]
max_line_length=off
trim_trailing_whitespace=false
.github/CODEOWNERS
+12
View File
@@ -0,0 +1,12 @@
# Each line is a file pattern followed by one or more owners.
# These owners will be the default owners for everything in the repo.
* @jrgarciadev
# Order is important. The last matching pattern has the most precedence.
# So if a pull request only touches javascript files, only these owners
# will be requested to review.
# *.js @octocat @github/js
# You can also use email addresses if you prefer.
# docs/* docs@example.com
.github/FUNDING.yml
+13
View File
@@ -0,0 +1,13 @@
# These are supported funding model platforms
github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
patreon: # Replace with a single Patreon username
open_collective: heroui
ko_fi: # Replace with a single Ko-fi username
tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
liberapay: # Replace with a single Liberapay username
issuehunt: # Replace with a single IssueHunt username
otechie: # Replace with a single Otechie username
lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']
.github/ISSUE_TEMPLATE/bug_report.yml
+114
View File
@@ -0,0 +1,114 @@
name: "Bug report"
title: "[BUG] - YOUR_ISSUE_TITLE_HERE_REPLACE_ME"
description: Create a report to help us improve
labels: [bug]
body:
- type: markdown
attributes:
value: |
Thank you for reporting an issue :pray:.
This issue tracker is for reporting bugs found in [HeroUI github repository](https://github.com/heroui-inc/heroui/)
If you have a question about how to achieve something and are struggling, please post a question
inside of either of the following places:
- HeroUI's [Discussion's tab](https://github.com/heroui-inc/heroui/discussions)
- HeroUI's [Discord channel](https://discord.gg/9b6yyZKmH4)
Before submitting a new bug/issue, please check the links below to see if there is a solution or question posted there already:
- HeroUI's [Issue's tab](https://github.com/heroui-inc/heroui/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc)
- HeroUI's [closed issues tab](https://github.com/heroui-inc/heroui/issues?q=is%3Aissue+sort%3Aupdated-desc+is%3Aclosed)
- HeroUI's [Discussions tab](https://github.com/heroui-inc/heroui/discussions)
The more information you fill in, the better the community can help you.
- type: input
id: version
attributes:
label: HeroUI Version
description: |
Please provide the version of HeroUI you are using (e.g. 3.0.5). Do NOT just put "latest" or "latest version".
placeholder: ex. 3.0.5
validations:
required: true
- type: textarea
id: description
attributes:
label: Describe the bug
description: |
Provide a clear and concise description of the challenge you are running into.
placeholder: |
This issue page is ONLY for HeroUI's core library. If you are facing an issue with a specific product, please refer to the following links:
- HeroUI Pro: Report in HeroUI Pro Discord Channel or Contact Support in Pro Dashboard
- HeroUI CLI: Report in https://github.com/heroui-inc/heroui-cli/issues
- HeroUI Native: Report in https://github.com/heroui-inc/heroui-native/issues
- Tailwind Variants: Report in https://github.com/heroui-inc/tailwind-variants/issues
validations:
required: true
- type: input
id: link
attributes:
label: Your Example Website or App
description: |
Which website or app were you using when the bug happened?
Note:
- Your bug will may get fixed much faster if we can run your code and it doesn't have dependencies other than the `@heroui/react` npm package.
- To create a shareable code example you can use Stackblitz (https://stackblitz.com/). Please no localhost URLs.
- Please read these tips for providing a minimal example: https://stackoverflow.com/help/mcve.
placeholder: |
e.g. https://stackblitz.com/edit/...... OR Github Repo
validations:
required: false
- type: textarea
id: steps
attributes:
label: Steps to Reproduce the Bug or Issue
description: Describe the steps we have to take to reproduce the behavior.
placeholder: |
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error
validations:
required: true
- type: textarea
id: expected
attributes:
label: Expected behavior
description: Provide a clear and concise description of what you expected to happen.
placeholder: |
As a user, I expected ___ behavior but i am seeing ___
validations:
required: true
- type: textarea
id: screenshots_or_videos
attributes:
label: Screenshots or Videos
description: |
If applicable, add screenshots or a video to help explain your problem.
For more information on the supported file image/file types and the file size limits, please refer
to the following link: https://docs.github.com/en/github/writing-on-github/working-with-advanced-formatting/attaching-files
placeholder: |
You can drag your video or image files inside of this editor ↓
- type: input
id: os
attributes:
label: Operating System Version
description: What operating system are you using?
placeholder: |
- OS: [e.g. macOS, Windows, Linux]
validations:
required: true
- type: dropdown
id: browser_type
attributes:
label: Browser
description: Select the browsers where the issue can be reproduced (that you know of).
options:
- "Chrome"
- "Firefox"
- "Safari"
- "Edge"
- "Opera"
- "Other (add additional context)"
validations:
required: true
.github/ISSUE_TEMPLATE/config.yml
+14
View File
@@ -0,0 +1,14 @@
blank_issues_enabled: true
contact_links:
- name: 💡 Feature Request
url: https://github.com/heroui-inc/heroui/discussions/categories/feature-requests
about: 💡 Suggest a new component, improve an existing component and etc
- name: 🤔 Long question or ideas?
url: https://github.com/heroui-inc/heroui/discussions
about: Ask long-form questions and discuss ideas.
- name: 💬 Discord Community Chat
url: https://discord.gg/9b6yyZKmH4
about: Ask quick questions or simply chat on the `HeroUI` community Discord server.
- name: 💬 New Updates (X)
url: https://x.com/hero_ui
about: Link to our X account if you want to follow us and stay up to date with HeroUI news
.github/common-actions/install/action.yml
+41
View File
@@ -0,0 +1,41 @@
name: "Install"
description: "Sets up Node.js and runs install"
runs:
using: composite
steps:
- name: Setup pnpm
uses: pnpm/action-setup@v6
with:
run_install: false
- name: Setup node
uses: actions/setup-node@v6
with:
cache: "pnpm"
check-latest: true
node-version-file: ".nvmrc"
registry-url: "https://registry.npmjs.org"
- name: Get pnpm store directory
shell: bash
run: |
echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
- name: Setup pnpm cache
uses: actions/cache@v5
with:
path: ${{ env.STORE_PATH }}
key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
restore-keys: |
${{ runner.os }}-pnpm-store-
- name: Install dependencies
shell: bash
run: pnpm install --frozen-lockfile
- name: Setup Git User
shell: bash
run: |
git config --global user.email "jrgarciadev@gmail.com"
git config --global user.name "Junior Garcia"
.github/pull_request_template.md
+28
View File
@@ -0,0 +1,28 @@
<!---
Thanks for creating a Pull Request ❤️!
Please read the following before submitting:
- PRs that adds new external dependencies might take a while to review.
- Keep your PR as small as possible.
- Limit your PR to one type (docs, feature, refactoring, ci, repo, or bugfix)
-->
Closes # <!-- Github issue # here -->
## 📝 Description
<!--- Add a brief description -->
## ⛳️ Current behavior (updates)
<!--- Please describe the current behavior that you are modifying -->
## 🚀 New behavior
<!--- Please describe the behavior or changes this PR adds -->
## 💣 Is this a breaking change (Yes/No):
<!-- If Yes, please describe the impact and migration path for existing HeroUI users. -->
## 📝 Additional Information
.github/workflows/QA.yaml
+71
View File
@@ -0,0 +1,71 @@
name: QA
on:
pull_request:
branches:
- canary
- v3*
- "beta-*"
- "rc-*"
jobs:
build:
name: Build
runs-on: ubuntu-latest
steps:
- name: Checkout branch
uses: actions/checkout@v6
- name: Install
uses: ./.github/common-actions/install
- name: Build packages
run: pnpm build
eslint:
name: ESLint
runs-on: ubuntu-latest
steps:
- name: Checkout branch
uses: actions/checkout@v6
- name: Install
uses: ./.github/common-actions/install
- name: Run ESLint
run: pnpm lint
types:
name: TypeScript
runs-on: ubuntu-latest
steps:
- name: Checkout branch
uses: actions/checkout@v6
- name: Install
uses: ./.github/common-actions/install
- name: Run typecheck
run: pnpm typecheck
continuous-release:
name: Continuous Release
if: github.repository == 'heroui-inc/heroui'
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- name: Checkout branch
uses: actions/checkout@v6
with:
fetch-depth: 0
- name: Install
uses: ./.github/common-actions/install
- name: Build packages
run: pnpm build
- name: Release
run: pnpx pkg-pr-new publish --pnpm './packages/styles' './packages/react'
.github/workflows/release.yml
+69
View File
@@ -0,0 +1,69 @@
name: Release
on:
push:
tags:
- "v*"
workflow_dispatch:
inputs:
dry_run:
description: "Dry run (publish without actually uploading to npm)"
required: false
type: boolean
default: false
jobs:
release:
runs-on: ubuntu-latest
environment: npm-publish
timeout-minutes: 15
permissions:
contents: write
id-token: write
steps:
- name: Checkout
uses: actions/checkout@v6
with:
fetch-depth: 0
- name: Install
uses: ./.github/common-actions/install
- name: Build packages
run: pnpm build
- name: Ensure npm supports trusted publishing
run: npm install -g npm@11
- name: Determine previous tag
id: prev-tag
run: |
PREV=$(git tag -l 'v*' --sort=-v:refname | grep -v "$(git describe --tags --exact-match 2>/dev/null || echo '')" | head -1)
echo "tag=${PREV:-}" >> $GITHUB_OUTPUT
echo "Previous tag: ${PREV:-none}"
- name: Create GitHub Release
if: ${{ !inputs.dry_run }}
run: npx changelogithub --from ${{ steps.prev-tag.outputs.tag }}
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
continue-on-error: true
- name: Publish @heroui/styles
id: publish-styles
working-directory: packages/styles
run: |
mkdir -p "$RUNNER_TEMP/heroui-release"
PACKAGE_TARBALL="$(node -p "const pkg = require('./package.json'); pkg.name.replace('@', '').replace('/', '-') + '-' + pkg.version + '.tgz'")"
pnpm pack --pack-destination "$RUNNER_TEMP/heroui-release"
npm publish "$RUNNER_TEMP/heroui-release/$PACKAGE_TARBALL" --access public ${{ inputs.dry_run && '--dry-run' || '' }}
- name: Publish @heroui/react
if: steps.publish-styles.outcome == 'success'
working-directory: packages/react
run: |
mkdir -p "$RUNNER_TEMP/heroui-release"
PACKAGE_TARBALL="$(node -p "const pkg = require('./package.json'); pkg.name.replace('@', '').replace('/', '-') + '-' + pkg.version + '.tgz'")"
pnpm pack --pack-destination "$RUNNER_TEMP/heroui-release"
npm publish "$RUNNER_TEMP/heroui-release/$PACKAGE_TARBALL" --access public ${{ inputs.dry_run && '--dry-run' || '' }}
.github/workflows/trigger-mcp-extraction.yml
+50
View File
@@ -0,0 +1,50 @@
name: Trigger MCP Extraction on Vercel Deployment
on:
repository_dispatch:
types:
- vercel.deployment.success
- vercel.deployment.promoted
jobs:
trigger-extraction:
name: Trigger MCP Extraction
runs-on: ubuntu-latest
steps:
- name: Trigger Native MCP Extraction
if: |
github.event.client_payload.git.ref == 'v3' ||
github.event.client_payload.git.ref == 'refs/heads/v3'
uses: peter-evans/repository-dispatch@v3
with:
token: ${{ secrets.MCP_DISPATCH_TOKEN }}
repository: heroui-inc/heroui-mcp
event-type: native-docs-deployed
client-payload: |
{
"environment": "production",
"deployment_url": "${{ github.event.client_payload.url }}",
"deployment_id": "${{ github.event.client_payload.id }}",
"git_ref": "${{ github.event.client_payload.git.ref }}",
"git_sha": "${{ github.event.client_payload.git.sha }}",
"triggered_by": "vercel_deployment"
}
- name: Trigger React MCP Extraction
if: |
github.event.client_payload.git.ref == 'v3' ||
github.event.client_payload.git.ref == 'refs/heads/v3'
uses: peter-evans/repository-dispatch@v3
with:
token: ${{ secrets.MCP_DISPATCH_TOKEN }}
repository: heroui-inc/heroui-mcp
event-type: react-docs-deployed
client-payload: |
{
"environment": "production",
"deployment_url": "${{ github.event.client_payload.url }}",
"deployment_id": "${{ github.event.client_payload.id }}",
"git_ref": "${{ github.event.client_payload.git.ref }}",
"git_sha": "${{ github.event.client_payload.git.sha }}",
"triggered_by": "vercel_deployment"
}
.github/workflows/update-stats.yml
+42
View File
@@ -0,0 +1,42 @@
name: Update Stats
on:
schedule:
# Runs every Monday at 00:00 UTC
- cron: "0 0 * * 1"
# Allow manual trigger
workflow_dispatch:
jobs:
update-stats:
name: Update Stats
runs-on: ubuntu-latest
steps:
- name: Checkout branch
uses: actions/checkout@v6
- name: Install
uses: ./.github/common-actions/install
- name: Update search metadata
run: pnpm update:search-meta
- name: Update GitHub info
run: pnpm update:github-info
- name: Create Pull Request
uses: peter-evans/create-pull-request@v8
with:
commit-message: "chore(stats): update project statistics"
title: "chore(stats): 📊 Update project statistics"
body: |
This PR updates the project statistics including:
- Search metadata
- GitHub repository information
This is an automated PR generated weekly.
branch: chore/update-stats
base: main
delete-branch: true
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
.gitignore
+93
View File
@@ -0,0 +1,93 @@
# cache
.turbo
.cache
.rollup.cache
.swc
# dependencies
node_modules
.pnp
.pnp.js
# testing
coverage
__snapshots__
coverage.json
# next.js
.next
out
.vercel
# production
build
dist
# debug
npm-debug.log*
yarn-debug.log*
yarn-error.log*
# typescript
*.tsbuildinfo
next-env.d.ts
# envs
.env
.env.local
.env.development
.env.development.local
.env.test
.env.test.local
.env.production
.env.production.local
.env*
.env*.local
.env*.local
.env*.staging
.env*.production
!.env.example
# idea
.idea
# temporary
.temp
# fumadocs
.source
# content layer
.contentlayer
.content-collections
# sitemaps
sitemap*.xml
# vite
vite.config.ts.timestamp-*
# storybook
*storybook.log
storybook-static
# misc
.DS_Store
*.pem
# bundle size reports
bundle-sizes.json
# clean-package backups
.package.json.backup
# Generated folder after running `pnpm pack`
package
storybook-static
# Pre-built skill tarballs (generated during build)
apps/docs/public/skills
# SEO analysis output
.seo-output
.husky/commit-msg
Executable
+1
View File
@@ -0,0 +1 @@
pnpm commitlint --config commitlint.config.mjs --edit ${1}
.husky/post-merge
Executable
+1
View File
@@ -0,0 +1 @@
. "$(dirname -- "$0")/scripts/pnpm-install"
.husky/post-rebase
Executable
+1
View File
@@ -0,0 +1 @@
. "$(dirname -- "$0")/scripts/pnpm-install"
.husky/pre-commit
Executable
+1
View File
@@ -0,0 +1 @@
pnpm lint-staged -c lint-staged.config.mjs
.husky/scripts/pnpm-install
+14
View File
@@ -0,0 +1,14 @@
#!/usr/bin/env sh
changed_files="$(git diff-tree -r --name-only --no-commit-id ORIG_HEAD HEAD)"
check_run() {
if echo "$changed_files" | grep --quiet "$1"; then
printf "\033[32m🔄 [husky] %s changed → running: %s\033[0m\n" "$1" "$2"
$2
else
printf "\033[90m⏭️ [husky] %s unchanged → skipping: %s\033[0m\n" "$1" "$2"
fi
}
check_run "pnpm-lock.yaml" "pnpm install --color"
.npmrc
+5
View File
@@ -0,0 +1,5 @@
auto-install-peers=true
enable-pre-post-scripts=true
lockfile=true
save-exact=true
strict-peer-dependencies=false
.nvmrc
+1
View File
@@ -0,0 +1 @@
v22.14.0
.prettierignore
+32
View File
@@ -0,0 +1,32 @@
**/.temp
**/.next
**/.swc
**/.turbo
**/.cache
**/.build
**/.vercel
**/dist
**/build
**/storybook-static
.rollup.cache
.rollup.cache/**
**/node_modules/
**/public/*
pnpm-lock.yaml
**/.contentlayer/
**/.source/**
**/coverage
**/__snapshots__
**/.DS_Store
**/.changeset
**/*.md
**/*.mdx
!public/manifest.json
!.vscode
!scripts
!.*.js
!.*.cjs
!.*.mjs
!.*.ts
!contentlayer.config.ts
!next-sitemap.config.ts
.vscode/extensions.json
Vendored
+9
View File
@@ -0,0 +1,9 @@
{
"recommendations": [
"bradlc.vscode-tailwindcss",
"editorconfig.editorconfig",
"dbaeumer.vscode-eslint",
"esbenp.prettier-vscode",
"unifiedjs.vscode-mdx"
]
}
.vscode/settings.json
Vendored
+48
View File
@@ -0,0 +1,48 @@
{
"npm.packageManager": "pnpm",
"css.lint.emptyRules": "ignore",
"css.lint.unknownAtRules": "ignore",
"scss.lint.unknownAtRules": "ignore",
"typescript.tsdk": "node_modules/typescript/lib",
"prettier.prettierPath": "node_modules/prettier",
"typescript.enablePromptUseWorkspaceTsdk": true,
"eslint.workingDirectories": [{"mode": "auto"}],
"eslint.options": {"flags": ["v10_config_lookup_from_file"]},
"editor.formatOnSave": false,
"editor.codeActionsOnSave": {
"source.fixAll.eslint": "explicit"
},
"files.associations": {
"**/.vscode/*.json": "jsonc"
},
"[html]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[css]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[scss]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[json]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[jsonc]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"tailwindCSS.classFunctions": ["tv", "clsx", "cn"],
"tailwindCSS.classAttributes": ["className", "classNames"],
"tailwindCSS.experimental.configFile": {
"packages/storybook/styles/globals.css": [
"apps/**",
"packages/react/**",
"packages/storybook/**",
"packages/styles/**"
]
}
}
AGENTS.md
+294
View File
@@ -0,0 +1,294 @@
# AGENTS.md
Instructions for AI agents working with the HeroUI v3 repository.
## Repository Overview
HeroUI v3 is a modern React UI library built with **Tailwind CSS v4**, organized as a **pnpm monorepo** managed by **Turborepo**. Components are built on top of [React Aria Components](https://react-spectrum.adobe.com/react-aria/) and follow a compound component pattern similar to Radix UI.
### Tech Stack
| Technology | Version | Purpose |
|---|---|---|
| Node.js | 22+ | Runtime |
| pnpm | 10.26.2 | Package manager (via corepack) |
| React | 19+ | UI framework |
| Tailwind CSS | 4.x | Styling |
| TypeScript | 5.x | Type safety |
| Turborepo | 2.x | Build orchestration |
| Storybook | Latest | Component development |
| Vitest | 4.x | Testing |
| React Aria Components | Latest | Accessibility primitives |
| tailwind-variants | Latest | Variant-based styling (includes twMerge) |
### Monorepo Structure
```
/
├── apps/
│ └── docs/ # Documentation site (Next.js + Fumadocs)
├── packages/
│ ├── react/ # Main UI library (@heroui/react)
│ │ ├── src/components/ # All components
│ │ ├── src/utils/ # Shared utilities
│ │ └── scripts/ # Build & codegen scripts
│ ├── styles/ # CSS styles & variants (@heroui/styles)
│ │ └── src/components/ # Per-component .css files
│ ├── standard/ # Shared ESLint, Prettier, TS configs
│ ├── storybook/ # Storybook configuration
│ └── vitest/ # Shared Vitest configurations
├── turbo.json
└── pnpm-workspace.yaml
```
## Commands
| Action | Command |
|---|---|
| Install dependencies | `pnpm i --hoist` |
| Build all packages | `pnpm build` |
| Build specific package | `pnpm build --filter=@heroui/react` |
| Dev (Storybook, port 6006) | `pnpm dev` |
| Dev (Docs site, port 3000) | `pnpm dev:docs` |
| Lint | `pnpm lint` |
| Typecheck | `pnpm typecheck` |
| Test all | `pnpm test` |
| Test one component | `pnpm test button` |
| Format | `pnpm run format` |
| Bump version | `pnpm version:bump` |
| Scaffold a new component | `cd packages/react && pnpm add:component ComponentName` |
## Git Commit Convention
All commits must follow [Conventional Commits](https://www.conventionalcommits.org/) and are validated by Husky + commitlint. Pre-commit also runs `lint-staged`.
```
<type>(<scope>): <message>
```
**Allowed types:** `feat`, `feature`, `fix`, `refactor`, `docs`, `build`, `test`, `ci`, `chore`
Examples:
```
feat(components): add select component
fix(button): resolve disabled state not applying
docs: update installation guide
```
## Component Architecture
### File Structure
Each component lives in `packages/react/src/components/<component-name>/`:
```
component-name/
├── component-name.tsx # Component implementation (uses React Aria)
├── component-name.styles.ts # Tailwind Variants styling
├── component-name.stories.tsx # Storybook stories
└── index.ts # Barrel exports
```
CSS styles live in `packages/styles/src/components/<component-name>/`.
### Creating a New Component
Always use the scaffold script:
```bash
cd packages/react
pnpm add:component ComponentName
```
Then build to update package.json exports:
```bash
pnpm build
```
### Compound Component Pattern
HeroUI uses a compound component pattern. Each component exports its sub-parts so users can compose and style them independently.
```tsx
// Context shares state/styles across parts
const ComponentContext = createContext<{slots?: ReturnType<typeof componentVariants>}>({});
// Root wraps children with context
const ComponentRoot = forwardRef(({children, className, ...props}, ref) => {
const slots = useMemo(() => componentVariants({...}), [...]);
return (
<ComponentContext value={{slots}}>
<ReactAriaPrimitive ref={ref} className={composeTwRenderProps(className, slots.base())}>
{children}
</ReactAriaPrimitive>
</ComponentContext>
);
});
// Child parts consume context
const ComponentItem = forwardRef(({className, ...props}, ref) => {
const {slots} = useContext(ComponentContext);
return (
<ReactAriaPrimitive ref={ref} className={composeTwRenderProps(className, slots?.item())}>
{props.children}
</ReactAriaPrimitive>
);
});
```
Compound components are exported via `Object.assign` as the default export:
```tsx
const CompoundComponent = Object.assign(ComponentRoot, {
Item: ComponentItem,
Trigger: ComponentTrigger,
});
export default CompoundComponent;
```
### Export Strategy
```tsx
// Named exports for compound components
export * as ComponentName from "./component-name";
// Direct exports for simple components
export {Component, type ComponentProps} from "./component";
// Always export variants
export {componentVariants, type ComponentVariants} from "./component.styles";
```
### Styling Rules
1. **Styles go in `.styles.ts` files**, never in `.tsx` files. Use `tv()` from `tailwind-variants`.
2. **Import from `tailwind-variants`**, never from `@heroui/standard`.
3. **Never use `twMerge` manually** — `tailwind-variants` already includes it.
4. **Add `"use client"` directive** at the top of every component `.tsx` file.
5. **Display names** follow: `HeroUI.ComponentName` or `HeroUI.Component.SubPart`.
### CSS / BEM Naming
Components use BEM-style CSS class names:
- **Block**: `button`, `card`, `alert`
- **Element**: `card__header`, `alert__icon`
- **Modifier**: `button--primary`, `button--lg`, `button--icon-only`
### Default Size Pattern (Critical)
All components must include default sizes in base classes so they work without explicit size props:
```css
.avatar {
@apply relative flex size-10 shrink-0 overflow-hidden rounded-full;
/* size-10 is the default (equivalent to --md) */
}
.avatar--sm { @apply size-8; }
.avatar--md { /* empty — this IS the default */ }
.avatar--lg { @apply size-12; }
```
### Interactive State Pattern
All interactive components must support both pseudo-classes and data attributes:
```css
.component {
&:hover,
&[data-hovered="true"] { @apply ...; }
&:active,
&[data-pressed="true"] { @apply ...; }
&:focus-visible,
&[data-focus-visible="true"] {
outline: 2px solid var(--focus);
outline-offset: 2px;
}
}
```
### React Aria className Patterns
React Aria components differ in how they accept `className`:
- **Render-prop components** (Button, Checkbox, Switch, Popover, Tooltip, Tabs, Link, Menu, etc.) — use `composeTwRenderProps(className, slots.foo())`.
- **String-only components** (Label, Text, Input, TextArea, Heading, Dialog) — pass `className` directly: `slots?.label({className})`.
### Composition Over Duplication
Do **not** create component-specific Label/Description/FieldError sub-components. Instead, compose with the existing shared primitives:
```tsx
import {Label} from "@/components/label";
import {Description} from "@/components/description";
<div className="flex items-center gap-3">
<Checkbox id="terms"><Checkbox.Indicator /></Checkbox>
<Label htmlFor="terms">Accept terms</Label>
</div>
```
### Tailwind Class Detection
Tailwind CSS scans files as plain text. **Never construct class names dynamically**:
```tsx
// BAD — Tailwind won't detect this
<div className={`text-${color}-600`} />
<span className={`button--${size}`} />
// GOOD — use complete class name mappings
const colorClasses = {
blue: "text-blue-600",
red: "text-red-600",
};
```
### Storybook
All stories must use the `"Components"` group in their title:
```tsx
export default { title: "Components/Button" };
```
Storybook is the primary dev workflow — run with `pnpm dev` (port 6006).
### Icon Library
HeroUI uses **Iconify** with **gravity-ui** as the default icon set.
## Current Components
### Completed
accordion, alert, alert-dialog, autocomplete, avatar, badge, breadcrumbs, button, button-group, card, checkbox, checkbox-group, chip, close-button, color-area, color-field, color-picker, color-slider, color-swatch, color-swatch-picker, combo-box, date-field, date-picker, date-range-picker, description, disclosure, disclosure-group, drawer, dropdown, empty-state, error-message, field-error, fieldset, form, header, input, input-group, input-otp, kbd, label, link, list-box, list-box-item, list-box-section, menu, menu-item, menu-section, meter, modal, number-field, pagination, popover, progress-bar, progress-circle, radio, radio-group, scroll-shadow, search-field, select, separator, skeleton, slider, spinner, surface, switch, switch-group, table, tabs, tag, tag-group, textarea, textfield, time-field, toast, toggle-button, toggle-button-group, toolbar, tooltip, typography
### In Progress
calendar, calendar-year-picker, range-calendar
## Non-obvious Gotchas
1. **`pnpm i` triggers builds** — The `postinstall` hook builds `@heroui/styles` and runs `typegen:docs`. If it fails, run `pnpm --filter @heroui/styles build` manually.
2. **Build order matters** — `@heroui/styles` must build before `@heroui/react`. Running `pnpm build` from root handles this via Turbo's `^build` dependency.
3. **Native addons allowlist** — The `pnpm.onlyBuiltDependencies` field in root `package.json` allows native compilation for `esbuild`, `@swc/core`, `@parcel/watcher`, etc. If this field is missing, you'll see "Ignored build scripts" warnings.
4. **No tests yet** — `pnpm test` runs but finds no test files. The Vitest config exists at `packages/vitest`.
5. **Commit hooks** — Husky runs `lint-staged` on pre-commit and `commitlint` on commit-msg. Non-conforming commits are rejected.
6. **Run checks before committing** — `pnpm lint && pnpm typecheck`
## Cursor Cloud Specific
- **Node.js v22+** is installed via binary tarball to `/usr/local/`.
- **pnpm** is activated via `corepack` — the `packageManager` field in root `package.json` declares `pnpm@10.26.2`.
- Full command reference and component architecture details are also in `CLAUDE.md`.
CLAUDE.md
+816
View File
@@ -0,0 +1,816 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Repository Overview
HeroUI v3 is a modern React UI library built with Tailwind CSS v4, using a pnpm monorepo structure managed by Turborepo.
### Key Technical Stack
- **Node.js**: v22+ required
- **pnpm**: v10.9.0 (package manager)
- **React**: v19+
- **Tailwind CSS**: v4.1.4
- **TypeScript**: v5.8.3
- **Turborepo**: Build orchestration
- **Storybook**: Component development
- **Vitest**: Testing framework
## Development Commands
### Core Development Commands
```bash
# Install dependencies (use --hoist flag)
pnpm i --hoist
# Start Storybook for component development
pnpm dev
# Start documentation site
pnpm dev:docs
# Build all packages
pnpm build
# Build specific package
pnpm build --filter=@heroui/react
# Run linting
pnpm lint
# Run tests
pnpm test
# Test specific component
pnpm test button
# Run formatting
pnpm run format
# Run type checking
pnpm typecheck
```
### Package-Specific Commands
- Use `--filter` flag with package name: `pnpm build --filter=@heroui/react`
- Main packages: `@heroui/react`, `@heroui/docs`, `@heroui/storybook`
## Git Commit Convention
**IMPORTANT**: This repository uses conventional commits with strict validation. All commits must follow this format:
```
<type>(<scope>): <message>
```
### Allowed Types:
- `feat` / `feature`: New features
- `fix`: Bug fixes
- `refactor`: Code refactoring
- `docs`: Documentation changes
- `build`: Build system changes
- `test`: Test changes
- `ci`: CI configuration changes
- `chore`: Other changes
### Examples:
```bash
git commit -m "feat(components): add new prop to avatar component"
git commit -m "fix(button): resolve click handler issue"
git commit -m "docs: update installation guide"
git commit -m "ci: add Claude Code GitHub Action workflow"
```
**Note**: Commits without proper format will be rejected by git hooks.
## Repository Architecture
### Monorepo Structure
```
/
├── apps/
│ └── docs/ # Documentation site (Next.js + Fumadocs)
├── packages/
│ ├── react/ # Main UI component library
│ ├── standard/ # Shared ESLint, Prettier, TypeScript configs
│ ├── storybook/ # Storybook configuration
│ └── vitest/ # Shared Vitest configurations
├── turbo.json # Turborepo configuration
└── pnpm-workspace.yaml # Workspace definition
```
### Component Architecture Pattern
Each component in `packages/react/src/components/` follows this structure:
```
component-name/
├── component-name.tsx # Main component (uses React Aria)
├── component-name.styles.ts # Tailwind Variants styling
├── component-name.stories.tsx # Storybook stories (title: "Components/ComponentName")
└── index.ts # Barrel exports
```
**IMPORTANT**: All Storybook stories must use the "Components" group in their title. For example: `title: "Components/Card"`, `title: "Components/Button"`, etc.
### CSS Class Naming Convention
**IMPORTANT**: HeroUI v3 uses BEM (Block Element Modifier) style for CSS classes to ensure predictable and maintainable styling:
- **Block**: The main component class (e.g., `button`, `card`, `alert`)
- **Modifier**: Variations of the component using double dashes (e.g., `button--primary`, `button--lg`, `button--icon-only`)
- **Element**: Child elements within a component (e.g., `card__header`, `alert__icon`)
**Migration to CSS-based Styling**:
- The `button` component has been migrated to use CSS styles from `@heroui/styles/src/components/button.css`
- This approach allows for better customization through CSS utilities and `@utility` directives
- Other components will gradually be migrated to follow this CSS-based pattern
- Components use `tv()` from `tailwind-variants` to map variant props to BEM class names
**Default Size Pattern**:
**CRITICAL**: All components MUST include default sizes in their base classes to prevent broken appearances when no size modifier is specified. Following the following pattern:
- **Base classes** include default dimensions (equivalent to the `--md` variant)
- **Medium variants** (`--md`) are empty with explanatory comments
- **Size modifiers** override the defaults when specified
Example implementation:
```css
/* Base component with default size */
.avatar {
@apply relative flex size-10 shrink-0 overflow-hidden rounded-full;
/* size-10 is the default, equivalent to --md */
}
/* Size variants */
.avatar--sm {
@apply size-8; /* Override default */
}
.avatar--md {
/* No styles as this is the default size */
}
.avatar--lg {
@apply size-12; /* Override default */
}
```
This ensures components work properly without explicit size classes:
- `<div className="avatar">` → Works perfectly (size-10)
- `<div className="avatar avatar--lg">` → Override to large (size-12)
### Core Component Design Principles
**IMPORTANT**: HeroUI v3 follows a compound component pattern similar to Radix UI, built on top of React Aria Components primitives. This enables maximum flexibility and customization for users.
### React Aria Components Integration
**CRITICAL**: Before implementing any component, you MUST:
1. Visit React Aria Components docs: https://react-spectrum.adobe.com/react-aria/
2. Study the specific component's API and examples
3. Understand its accessibility features and ARIA patterns
4. Plan the transformation from React Aria's prop-based API to Radix UI's composition-based API
React Aria provides the accessibility foundation, but we transform their API to match Radix UI's compound component pattern for better customization.
#### 1. **Compound Component Pattern**:
- Export all internal component pieces (Root, Item, Trigger, Content, etc.)
- Each piece can be styled and composed independently
- Users can customize render logic without accessing internal code
- Examples: Accordion (Root, Item, Heading, Trigger, Panel, Indicator, Body), Alert (Root, Icon, Title, Description, Action, Close)
#### 2. **Export Strategy**:
```typescript
// Named exports for compound components
export * as ComponentName from "./component-name";
// Direct exports for simple components
export {Component, type ComponentProps} from "./component";
// Always export variants
export {componentVariants, type ComponentVariants} from "./component.styles";
```
#### 3. **Component Structure for Compound Components**:
```typescript
// Context for sharing state/styles
const ComponentContext = createContext<{slots?: ReturnType<typeof componentVariants>}>({});
// Root component wraps with context
const ComponentRoot = React.forwardRef<...>(({children, className, ...props}, ref) => {
const slots = React.useMemo(() => componentVariants({...}), [...]);
return (
<ComponentContext value={{slots}}>
<ReactAriaComponent ref={ref} className={composeTwRenderProps(className, slots.base())}>
{children}
</ReactAriaComponent>
</ComponentContext>
);
});
// Child components consume context
const ComponentItem = React.forwardRef<...>(({className, ...props}, ref) => {
const {slots} = useContext(ComponentContext);
return (
<ReactAriaComponent ref={ref} className={composeTwRenderProps(className, slots?.item())}>
{props.children}
</ReactAriaComponent>
);
});
// Export pattern
export {ComponentRoot as Root, ComponentItem as Item, ...};
```
#### 4. **Key Implementation Details**:
1. **Styling with Tailwind Variants**:
- Styles defined in `.styles.ts` files using `tv()` function from `tailwind-variants`
- **IMPORTANT**: Always import from `tailwind-variants`, never from `@heroui/standard` (which doesn't exist)
- **CRITICAL**: tailwind-variants already includes `twMerge` functionality, so NEVER manually use `twMerge`
- **RULE**: All component styles MUST be defined in separate `.styles.ts` files, NOT in the component implementation files
- Component implementation files (`.tsx`) should only contain logic and React Aria primitives
- Example imports:
```typescript
import type {VariantProps} from "tailwind-variants";
import {tv} from "tailwind-variants";
```
- Support for variants (primary, secondary, etc.)
- Compound variants for conditional styling
- Slot system for complex components
2. **Component Features**:
- Built on React Aria Components for accessibility
- Use `forwardRef` for all components
- Display names follow: `HeroUI.ComponentName` or `HeroUI.Component.SubPart`
- Support render props from React Aria when available
3. **Type Exports**:
```typescript
// Export props for each component part
export type ComponentRootProps = {...}
export type ComponentItemProps = {...}
export type ComponentVariants = VariantProps<typeof componentVariants>
```
4. **Utilities** (`packages/react/src/utils/`):
- `composeTwRenderProps`: Merge Tailwind classes with render props
- `focusRingClasses`: Consistent focus styling
- `disabledClasses`: Disabled state styling
- `mapPropsVariants`: Separate variant props from component props
5. **React Aria Components className Patterns**:
**CRITICAL**: React Aria components have different className prop behaviors:
**Components that support render props** (use `composeTwRenderProps`):
- Button, TextField, FieldError, Checkbox, CheckboxGroup
- Switch, RadioGroup, Radio, Slider (and Track, Thumb, Output)
- Popover, Tooltip, Tabs (and Tab, TabList, TabPanel)
- Link, Menu, MenuItem, Accordion (DisclosureGroup)
**Components that ONLY accept string className** (pass className directly):
- Label, Text, Input, TextArea
- Heading, Dialog, OverlayArrow
**Usage examples**:
```typescript
// For render prop components - use composeTwRenderProps
<ButtonPrimitive
className={composeTwRenderProps(className, slots?.button())}
/>
// For string-only components - pass className directly
<LabelPrimitive
className={slots?.label({className})}
/>
// OR
<LabelPrimitive
className={labelVariants({size, variant, className})}
/>
```
**How to check**: If unsure, check the React Aria docs or try both approaches - TypeScript will error if a component doesn't support render props
6. **Composition Pattern with Existing Components**:
**CRITICAL**: HeroUI follows a composition-based approach. Components should reuse existing primitives rather than creating component-specific versions.
**Key Principles**:
- **DO NOT** create component-specific Label, Description, or FieldError components
- **DO** reuse the existing `Label`, `Description`, and `FieldError` components
- **DO** use standard HTML composition patterns with `htmlFor`/`id` attributes
**Example Pattern**:
```typescript
// ❌ WRONG - Component-specific label
export const Checkbox = {
Root: CheckboxRoot,
Label: CheckboxLabel, // Don't create this!
};
// ✅ CORRECT - Compose with existing components
import { Label } from "@/components/label";
import { Description } from "@/components/description";
// Usage:
<div className="flex items-center gap-3">
<Checkbox id="terms">
<Checkbox.Indicator />
</Checkbox>
<Label htmlFor="terms">Accept terms</Label>
</div>
// With description:
<div className="flex gap-3">
<Checkbox className="mt-0.5" id="notifications">
<Checkbox.Indicator />
</Checkbox>
<div className="flex flex-col gap-1">
<Label htmlFor="notifications">Email notifications</Label>
<Description>Get notified when someone mentions you</Description>
</div>
</div>
```
**Components that follow this pattern**:
- Checkbox - uses external Label/Description
- Radio - uses external Label/Description
- Switch - uses external Label/Description
- TextField - provides slots for Label/Description/FieldError
### Current Components
- `accordion`: Collapsible content sections
- `alert`: Alert messages with compound components
- `avatar`: User avatars with Radix UI
- `button`: Button with variants and sizes
- `checkbox`: Checkbox with compound components (uses external Label/Description)
- `chip`: Small informational badges
- `description`: Description text for form fields
- `field-error`: Error messages for form fields
- `fieldset`: Form field grouping components (Fieldset, Legend, FieldGroup, Field, CheckboxField)
- `label`: Label text for form fields
- `link`: Styled anchor links
- `menu`: Dropdown menu system
- `popover`: Popover overlays
- `spinner`: Loading indicators
- `tabs`: Tab navigation
- `typography`: Typography component for headings, body copy, and prose
- `textfield`: Text input field with compound components
- `tooltip`: Hover tooltips
## Development Workflow
### Standard Feature Development Process
**IMPORTANT**: When working on any feature or improvement, Claude Code MUST follow this systematic workflow to ensure accuracy and code quality:
1. **Research Phase**:
- Thoroughly research the feature/component requirements
- Study relevant documentation (React Aria, Tailwind CSS, etc.)
- Analyze existing similar implementations in the codebase
- Identify all dependencies and integration points
2. **Planning Phase**:
- Create a detailed implementation plan with a comprehensive checklist
- Break down the task into specific, measurable steps
- Include testing and verification steps in the plan
- Present the plan for review before proceeding
3. **Review & Correction Phase**:
- Review the plan for completeness and accuracy
- Make necessary corrections or adjustments
- Ensure all edge cases are considered
- Confirm the plan aligns with HeroUI patterns and conventions
4. **Execution Phase**:
- Start executing the plan step by step
- Use the TodoWrite tool to track progress automatically
- Mark todos as in_progress when starting a task
- Mark todos as completed immediately after finishing each step
- Never batch completions - update status in real-time
5. **Verification Phase**:
- Manually verify all changes work as expected
- Test API calls if backend changes were made
- Check frontend rendering and interactions
- Run lint and type checks: `pnpm lint && pnpm typecheck`
- Ensure all tests pass: `pnpm test`
**Example Workflow**:
```
User: "Add a new Select component"
Claude:
1. Research: Studies React Aria Select, existing patterns
2. Plan: Creates detailed checklist with 15+ items
3. Review: Presents plan for feedback
4. Execute: Implements step-by-step with todo updates
5. Verify: Tests component, runs checks, confirms functionality
```
This workflow ensures thorough understanding, proper planning, and high-quality implementation with full transparency throughout the process.
### Component Development Workflow
1. **Creating New Components**:
**CRITICAL: Research & Design Phase**:
- **FIRST**: Check the Figma design for the component breakdown (e.g., Menu Container, Menu Item, etc.)
- **SECOND**: Research the React Aria Components documentation at https://react-spectrum.adobe.com/react-aria/
- Find the appropriate React Aria primitive (e.g., CheckboxGroup, Dialog, Select, etc.)
- Understand the React Aria API, props, and accessibility features
- Map Figma component pieces to React Aria components and plan the compound structure
- Plan how to adapt it to follow Radix UI's compound component pattern
**Component Creation - ALWAYS USE THE SCRIPT**:
```bash
# Navigate to packages/react directory
cd packages/react
# Use the add:component script
pnpm add:component ComponentName
# Examples:
pnpm add:component Menu
pnpm add:component Select
pnpm add:component DatePicker
```
This script will:
- Create all necessary files with proper structure
- Add the export to `src/components/index.ts`
- Generate boilerplate following HeroUI patterns
- Set up the component with TypeScript and proper exports
After creating the component:
```bash
# Build to update package.json exports automatically
pnpm build
```
**Implementation Steps**:
- Study existing HeroUI components (accordion, alert) to understand the compound pattern
- Use React Aria Components as the foundation for accessibility
- Transform React Aria's API to match Radix UI patterns:
- Single component → Multiple exported parts (Item, Trigger, Content, etc.)
- Props-based API → Composition-based API
- Internal state → Context-based state sharing
- Create Context for sharing styles across component parts
- Export ALL component parts for maximum customization
- Define styles in separate `.styles.ts` file with slot system
- Add "use client" directive at the top of component file
- Create comprehensive Storybook stories showing all variants and compositions
- Follow the export pattern: `export * as ComponentName from "./component-name"`
**Example Transformation**:
```typescript
// React Aria: Single component with props
<CheckboxGroup label="Options" value={selected} onChange={setSelected}>
<Checkbox value="1">Option 1</Checkbox>
</CheckboxGroup>
// HeroUI: Compound pattern
<CheckboxGroup value={selected} onValueChange={setSelected}>
<CheckboxGroup.Label>Options</CheckboxGroup.Label>
<CheckboxGroup.Item value="1">
<CheckboxGroup.Indicator />
<CheckboxGroup.Label>Option 1</CheckboxGroup.Label>
</CheckboxGroup.Item>
</CheckboxGroup>
```
**Example of a compound component exports**
```typescript
const CompoundAccordion = Object.assign(Accordion, {
Item: AccordionItem,
Heading: AccordionHeading,
Trigger: AccordionTrigger,
Panel: AccordionPanel,
Indicator: AccordionIndicator,
Body: AccordionBody,
});
export type {
AccordionProps,
AccordionItemProps,
AccordionTriggerProps,
AccordionPanelProps,
AccordionIndicatorProps,
AccordionBodyProps,
};
export default CompoundAccordion;
```
**IMPORTANT**: The compound component should be exported as the default export.
2. **Testing**:
- Run `pnpm test` for all tests
- Run `pnpm test <component>` for specific component
- Ensure all new features have tests
3. **Documentation**:
- Docs live in `apps/docs/content/`
- Uses MDX format
- HeroUI components are pre-imported
4. **Version Management**:
- Uses [bumpp](https://github.com/antfu/bumpp) for version bumping
- Run `pnpm version:bump` to interactively bump the version, commit, and tag
- Pushing a `v*` tag triggers the release CI workflow
- Follow semantic versioning
## Icon Library
**IMPORTANT**: HeroUI uses Iconify with gravity-ui as the default icon set.
## Important Notes
- Always prefer editing existing files over creating new ones
- **NEVER** create documentation files (_.md, _.mdx, README files) unless explicitly requested by the user
- Follow the established component patterns and conventions
- Ensure accessibility with React Aria Components
- Maintain TypeScript type safety
- Use the commit convention to avoid git hook failures
- Run lint and type checks before committing: `pnpm lint && pnpm typecheck`
## Tailwind CSS Class Detection Rules
**CRITICAL**: Tailwind CSS scans files as plain text and requires complete class names to be statically detectable.
### Key Rules:
1. **Never construct class names dynamically**
❌ **BAD** - Dynamic string concatenation:
```jsx
// These patterns will NOT work:
<div className={`text-${color}-600`} />
<button className={`bg-${variant}-500`} />
<span className={`button--${size}`} />
```
✅ **GOOD** - Complete class names:
```jsx
// Use complete strings or object mappings:
<div className={error ? "text-red-600" : "text-green-600"} />
```
2. **Use object mappings for dynamic classes**
❌ **BAD** - Props in template literals:
```jsx
function Button({color}) {
return <button className={`bg-${color}-600 hover:bg-${color}-500`} />;
}
```
✅ **GOOD** - Map props to complete classes:
```jsx
function Button({color}) {
const colorVariants = {
blue: "bg-blue-600 hover:bg-blue-500",
red: "bg-red-600 hover:bg-red-500",
};
return <button className={colorVariants[color]} />;
}
```
3. **For BEM-style classes, use complete mappings**
✅ **GOOD** - Complete class name mappings:
```jsx
const sizeClasses = {
sm: "button--sm",
md: "button--md",
lg: "button--lg",
};
// Use the mapping:
className={sizeClasses[size]}
```
### Why This Matters:
- Tailwind generates CSS only for classes it can detect in your source files
- Dynamic concatenation prevents Tailwind from finding the complete class names
- Missing classes = missing styles in production
## Figma Integration & MCP Server Rules
### Figma Dev Mode MCP Server
**IMPORTANT**: When creating components with Figma designs:
1. **Component Breakdown**: Figma designs are already broken down into component pieces (e.g., Menu Container, Menu Item, etc.). Use these as reference for:
- Component structure and naming (adapt to code conventions)
- Visual styling and spacing
- Component composition patterns
2. **MCP Server Rules**:
- The Figma Dev Mode MCP Server provides an assets endpoint for images and SVG assets
- **CRITICAL**: If the Figma MCP Server returns a localhost source for an image or SVG, use that source directly
- **DO NOT** import or add new icon packages - all assets should come from the Figma payload
- **DO NOT** use or create placeholders if a localhost source is provided
- Always use the actual assets from Figma MCP Server
3. **Workflow**:
- Check Figma for component visual design and breakdown
- Map Figma component names to appropriate React Aria primitives
- Use Figma assets (icons, images) directly from the MCP Server
- Implement styles based on Figma design tokens and specifications
## Library Documentation with Context7 MCP
**IMPORTANT**: We have the Context7 MCP server available (https://github.com/upstash/context7) for accessing up-to-date library documentation.
### When to Use Context7
Use Context7 MCP when working with external libraries, especially:
- **Tailwind CSS v4**: When working with Tailwind CSS v4 features, use Context7 to get the latest documentation at https://context7.com/context7/tailwindcss
- **Fumadocs**: When working on the documentation site in `apps/docs/`, use Context7 to get the latest Fumadocs framework documentation
- **Next.js**: For Next.js specific features and APIs used in the docs app
- Any other third-party libraries where up-to-date documentation is needed
### How to Use Context7
1. First, resolve the library ID using `mcp__context7__resolve-library-id`
2. Then fetch documentation using `mcp__context7__get-library-docs` with the resolved ID
3. This ensures you're always working with the latest documentation rather than outdated information
### Example Usage Areas
- Implementing new documentation features in `apps/docs/`
- Configuring Fumadocs settings in `source.config.ts`
- Working with MDX components and layouts
- Setting up search functionality
- Implementing documentation navigation and structure
## GitHub Repository Search with Grep MCP
**IMPORTANT**: We have the Grep MCP server available for searching over a million public GitHub repositories to find real-world code examples and patterns.
### When to Use Grep MCP
Use the Grep MCP (`mcp__grep__searchGitHub`) when tackling complex problems that require:
- **Real-world implementation examples**: Finding how other developers solve similar problems
- **Best practices and patterns**: Discovering production-ready code patterns
- **Library usage examples**: Understanding how specific APIs or libraries are used in practice
- **Complex integrations**: Seeing how different libraries work together
- **Error handling patterns**: Learning from battle-tested error handling approaches
### How to Use Grep MCP
The Grep MCP searches for **literal code patterns**, not keywords. Use actual code syntax:
**Good examples**:
- `'useState('` - Find React hooks usage
- `'import { tv } from "tailwind-variants"'` - Find tailwind-variants imports
- `'forwardRef<'` - Find forwardRef usage patterns
- `'(?s)useEffect\\(\\(\\) => {.*return.*}'` - Find useEffect with cleanup (regex)
**Bad examples**:
- `'react best practices'` - This is a keyword, not code
- `'how to use tailwind'` - Use actual import statements instead
### Example Use Cases
1. **Complex Component Patterns**:
- Search: `'compound.*component'` with language=['TypeScript', 'TSX']
- Find how others implement compound component patterns
2. **Accessibility Implementations**:
- Search: `'AriaProps'` or `'useAriaLabel'`
- Discover accessibility patterns in React apps
3. **Monorepo Configurations**:
- Search: `'pnpm-workspace.yaml'` with path='pnpm-workspace.yaml'
- Study monorepo setups similar to HeroUI
4. **Tailwind CSS v4 Patterns**:
- Search: `'@import "tailwindcss"'` with language=['CSS']
- Find Tailwind CSS v4 usage patterns
5. **React Aria Components Usage**:
- Search: `'from "react-aria-components"'`
- See how others integrate React Aria Components
### Best Practices
- Use language filters to narrow results (e.g., `language=['TypeScript', 'TSX']`)
- Use regex patterns with `useRegexp=true` for flexible matching
- Filter by well-known repositories for quality examples (e.g., `repo='vercel/'`)
- Combine with file path filters for specific file types
## Agent-Specific Guidelines
### For style-migrator and tailwind-v4-css-expert Agents
When working with HeroUI CSS components, follow these critical patterns:
#### Default Size Implementation
**REQUIRED**: All CSS components MUST follow the default size pattern:
1. **Base classes** include default dimensions equivalent to `--md` variant
2. **Medium variant** (`--md`) is an empty class with explanatory comment
3. **Size variants** override the base defaults
**Template for CSS components with size variants:**
```css
/* Base component styles */
.component {
/* Base styling */
@apply [base-styles];
/* Default size - matches component--md variant */
@apply [default-size-classes];
}
/* Size variants */
.component--sm {
@apply [small-size-overrides];
}
.component--md {
/* No styles as this is the default size */
}
.component--lg {
@apply [large-size-overrides];
}
```
#### Pseudo-Class Fallback Pattern
**REQUIRED**: All interactive components MUST include both pseudo-class and data-attribute support:
```css
/* Interactive states - both approaches */
.component {
/* Hover states */
&:hover,
&[data-hovered="true"] {
@apply [hover-styles];
}
/* Active/pressed states */
&:active,
&[data-pressed="true"] {
@apply [active-styles];
}
/* Focus states */
&:focus-visible,
&:focus:not(:focus-visible),
&[data-focus-visible="true"] {
outline: 2px solid var(--focus);
outline-offset: 2px;
}
}
```
#### Component Examples
- **button.css**: Base has `h-10 md:h-9`, empty `.button--md` variant
- **avatar.css**: Base has `size-10`, empty `.avatar--md` variant
- **spinner.css**: Base has `size-6`, empty `.spinner--md` variant
These patterns ensure components never appear broken and maintain consistency across the design system.
CODE_OF_CONDUCT.md
+46
View File
@@ -0,0 +1,46 @@
# Contributor Covenant Code of Conduct
## Our Pledge
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
## Our Standards
Examples of behavior that contributes to creating a positive environment include:
- Using welcoming and inclusive language
- Being respectful of differing viewpoints and experiences
- Gracefully accepting constructive criticism
- Focusing on what is best for the community
- Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
- The use of sexualized language or imagery and unwelcome sexual attention or advances
- Trolling, insulting/derogatory comments, and personal or political attacks
- Public or private harassment
- Publishing others' private information, such as a physical or electronic address, without explicit permission
- Other conduct which could reasonably be considered inappropriate in a professional setting
## Our Responsibilities
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
## Scope
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at jrgarciadev@gmail.com. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
[homepage]: http://contributor-covenant.org
[version]: http://contributor-covenant.org/version/1/4/
CONTRIBUTING.md
+232
View File
@@ -0,0 +1,232 @@
# HeroUI Contributing Guide
Hello!, I am very excited that you are interested in contributing with HeroUI. However, before submitting your contribution, be sure to take a moment and read the following guidelines.
- [Code of Conduct](https://github.com/heroui-inc/heroui/blob/canary/CODE_OF_CONDUCT.md)
- [Extraction request guidelines](#pull-request-guidelines)
- [Development Setup](#development-setup)
- [Tests](#tests)
- [Visual Changes](#visual-changes)
- [Documentation](#documentation)
- [Breaking Changes](#breaking-changes)
- [Becoming a maintainer](#becoming-a-maintainer)
### Tooling
- [PNPM](https://pnpm.io/) to manage packages and dependencies
- [Tsup](https://tsup.egoist.dev/) to bundle packages
- [Storybook](https://storybook.js.org/) for rapid UI component development and
testing
- [Testing Library](https://testing-library.com/) for testing components and
hooks
- [bumpp](https://github.com/antfu/bumpp) for version bumping and release
management.
### Commit Convention
Before you create a Pull Request, please check whether your commits comply with
the commit conventions used in this repository.
When you create a commit we kindly ask you to follow the convention
`category(scope or module): message` in your commit message while using one of
the following categories:
- `feat / feature`: all changes that introduce completely new code or new
features
- `fix`: changes that fix a bug (ideally you will additionally reference an
issue if present)
- `refactor`: any code related change that is not a fix nor a feature
- `docs`: changing existing or creating new documentation (i.e. README, docs for
usage of a lib or cli usage)
- `build`: all changes regarding the build of the software, changes to
dependencies or the addition of new dependencies
- `test`: all changes regarding tests (adding new tests or changing existing
ones)
- `ci`: all changes regarding the configuration of continuous integration (i.e.
github actions, ci system)
- `chore`: all changes to the repository that do not fit into any of the above
categories
e.g. `feat(components): add new prop to the avatar component`
If you are interested in the detailed specification you can visit
https://www.conventionalcommits.org/ or check out the
[Angular Commit Message Guidelines](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines).
## Pull Request Guidelines
- The `main` branch is basically a snapshot of the latest production version. All development must be done in dedicated branches and will be merged to `canary` branch.
- Make sure that Github Actions are green
- It is good to have multiple small commits while working on the PR. We'll let GitHub squash it automatically before the merge.
- If you add a new feature:
- Add the test case that accompanies it.
- Provide a compelling reason to add this feature. Ideally, I would first open a suggestion topic and green it before working on it.
- If you correct an error:
- If you are solving a special problem, add (fix #xxxx [, # xxx]) (# xxxx is the problem identification) in your PR title for a better launch record, for example update entities encoding / decoding (fix # 3899).
- Provide a detailed description of the error in the PR. Favorite live demo.
- Add the appropriate test coverage, if applicable.
### Steps to PR
1. Fork of the heroui repository and clone your fork
2. Create a new branch out of the `canary` branch. We follow the convention
`[type/scope]`. For example `fix/dropdown-hook` or `docs/menu-typo`. `type`
can be either `docs`, `fix`, `feat`, `build`, or any other conventional
commit type. `scope` is just a short id that describes the scope of work.
3. Make and commit your changes following the
[commit convention](https://github.com/heroui-inc/heroui/blob/main/CONTRIBUTING.md#commit-convention).
As you canary, you can run `pnpm build --filter=<module>` and
`pnpm test packages/<module>/<pkg>` e.g. `pnpm build --filter=avatar & pnpm test packages/components/avatar` to make sure everything works as expected.
> To know more about the `--filter` option, please check the turborepo [docs](https://turborepo.org/docs/core-concepts/filtering).
4. Version bumping is handled by maintainers using `pnpm version:bump` which
uses [bumpp](https://github.com/antfu/bumpp) to interactively bump the
version, create a git commit, and push a tag that triggers the release CI.
## Development Setup
After cloning the repository, execute the following commands in the root folder:
1. Install dependencies
```bash
pnpm i --hoist
#or
pnpm install --hoist
```
We use [Turbo Repo](https://turborepo.org/) for the project management.
2. If you will be working on the components source code, you can use the following command to start the webpack dev server:
```bash
## Start the dev babel server of HeroUI core components
pnpm dev
## optional
pnpm sb ## this will start the storybook server for a faster development and testing.
pnpm dev:docs ## this will start the documentation next.js server and it will automatically detect the changes in the components.
```
- If you will be working just on the documentation source code / mdx, you can use the following commands to build
HeroUI components and then start the next.js dev server:
```bash
## Build HeroUI source components
pnpm build
## Start the next.js documentation dev server
pnpm dev:docs
```
- You also can use Storybook to test the components and faster development:
```bash
pnpm sb
```
Remember that these commands must be executed in the root folder of the project.
3. Create a branch for your feature or fix:
```bash
# Move into a new branch for your feature
git checkout -b feat/thing
```
```bash
# Move into a new branch for your fix
git checkout -b fix/something
```
4. If your code passes all the tests, then push your feature/fix branch:
All commits that fix bugs or add features need a test.
You can run the nest command for component specific tests.
```bash
# Test current code
pnpm test
# or
npm run test
```
```bash
# Test isolated component code
pnpm test button
# or
npm run test button
```
5. Be sure the package builds.
```bash
# Build current code
pnpm build
# or
npm run build
```
> Note: ensure that you have at least Node.js 20.16.0 as well as pnpm 9.6.0 or higher installed on your machine to run the scripts
6. Send your pull request:
- Send your pull request to the `canary` branch
- Your pull request will be reviewed by the maintainers and the maintainers will decide if it is accepted or not
- Once the pull request is accepted, the maintainers will merge it to the `canary` branch
## Visual Changes
When making a visual change, please provide screenshots
and/or screencasts of the proposed change. This will help us to understand the
desired change easier.
Until HeroUI has a stable release new components will be created only for the core team.
## Documentation
Please update the docs with any API changes, the code and docs should always be in sync.
The main documentation lives in the `apps/docs/content` folder, the project uses MDX and all `HeroUI` are already imported.
## Breaking changes
Breaking changes should be accompanied with deprecations of removed functionality. The deprecated APIs themselves should not be removed until the minor release after that.
## Becoming a maintainer
If you are interested in becoming a HeroUI maintainer, start by
reviewing issues and pull requests. Answer questions for those in need of
troubleshooting. Join us in the
[Discord Community](https://discord.gg/9b6yyZKmH4) chat room.
Once we see you helping, either we will reach out and ask you if you want to
join or you can ask one of the current maintainers to add you. We will try our
best to be proactive in reaching out to those that are already helping out.
GitHub by default does not publicly state that you are a member of the
organization. Please feel free to change that setting for yourself so others
will know who's helping out. That can be configured on the [organization
list](https://github.com/orgs/heroui-inc/people) page.
Being a maintainer is not an obligation. You can help when you have time and be
less active when you don't. If you get a new job and get busy, that's alright.
LICENSE
+199
View File
@@ -0,0 +1,199 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to the Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by the Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding any notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. Please also get an approval
from the project maintainers before using the Apache License.
Copyright 2025 NextUI Inc.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
README.md
Symlink
+1
View File
@@ -0,0 +1 @@
packages/react/README.md
README.wehub.md
+7
View File
@@ -0,0 +1,7 @@
# WeHub 来源说明
- 原始项目：`nextui-org/nextui`
- 原始仓库：https://github.com/nextui-org/nextui
- 导入方式：上游默认分支的最新快照
- 原作者、版权和许可证信息以原始仓库及本仓库 LICENSE 为准
- 本文件仅用于记录来源，不代表 WeHub 是原项目作者
apps/docs/.env.example
+11
View File
@@ -0,0 +1,11 @@
NEXT_PUBLIC_APP_ENV="production,preview,development"
NEXT_PUBLIC_CDN_URL="<cdn-url>"
LOOPS_API_ENDPOINT="<LOOPS_API_ENDPOINT>"
LOOPS_API_KEY="<LOOPS_API_KEY>"
FEATUREBASE_API_ENDPOINT="<FEATUREBASE_API_ENDPOINT>"
FEATUREBASE_API_KEY="<FEATUREBASE_API_KEY>"
NEXT_PUBLIC_PRO_API_URL="<PRO_API_URL>"
NEXT_PUBLIC_PRO_URL="<PRO_URL>"
NEXT_PUBLIC_SHOW_PRE_SALE_BANNER="true"
NEXT_PUBLIC_POSTHOG_HOST="<POSTHOG_HOST>"
NEXT_PUBLIC_POSTHOG_KEY="<POSTHOG_KEY>"
apps/docs/.npmrc
+1
View File
@@ -0,0 +1 @@
enable-pre-post-scripts=true
apps/docs/content/blog/cn/best-react-ui-component-libraries.mdx
+266
View File
@@ -0,0 +1,266 @@
---
title: "2026 年 12 个最佳 React UI 组件库"
description: "对比 2026 年 12 个最佳 React UI 组件库：HeroUI、shadcn/ui、MUI、Chakra UI、Mantine 等。涵盖功能特性、可访问性与 AI 工具支持。"
date: "2026-05-16"
author: "Junior Garcia"
authorHandle: "@jrgarciadev"
authorUrl: "https://x.com/jrgarciadev"
authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4"
tags: ["react", "ui-libraries", "comparison"]
image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/blog/heroui-overview-light.png"
darkImage: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/blog/heorui-overview-dark.png"
---
选择合适的 React UI 组件库，会直接影响你的开发体验。2026 年最佳的 React UI 组件库都提供了开箱即用、可访问性良好的生产级组件，让你专注于产品功能，而不是第 N 次重新实现下拉菜单。
我从样式方案、可访问性基础、组件广度、AI 工作流支持和授权许可这几个维度，对比了 12 个库。各项目的组件数量与定价随时可能变化，因此请将本文视为一份实用的速查指南，最终决策前请查阅各自的官方文档。
<h2 className="blog-table-heading mt-10 text-xl font-semibold text-muted">速览对比</h2>
| 组件库 | 样式方案 | 可访问性基础 | 组件广度 | AI 工作流 |
|---------|---------|--------------------------|---------|-------------|
| **HeroUI** | Tailwind CSS v4 | React Aria | <ComponentCount />+ 个组件，<ExampleCount />+ 个示例 | MCP 服务器、llms.txt、agent skills |
| **shadcn/ui** | Tailwind CSS | Radix UI 及其他基础组件 | 官方文档列出 59 个组件条目 | MCP 服务器、llms.txt、skills |
| **Material UI** | 默认使用 Emotion，可接入 Pigment CSS | MUI 自研实现 | 核心组件 + MUI X，覆盖极广 | 公开文档 |
| **Chakra UI** | 基于 Panda CSS API 的体系 | Chakra / Ark UI 生态 | 应用层组件覆盖广泛 | MCP 服务器与公开文档 |
| **Mantine** | CSS 文件 / CSS Modules | Mantine 自研实现 | 120+ 个组件，70+ 个 hooks | MCP 服务器、llms.txt、skills |
| **Radix UI** | 无样式 | Radix 基础组件 | 聚焦基础组件 | 公开文档 |
| **Ant Design** | CSS-in-JS / Token 体系 | Ant Design 自研实现 | 偏企业级 | 公开文档 |
| **Headless UI** | 无样式 | Headless UI 基础组件 | 聚焦基础组件 | 公开文档 |
| **React Aria** | 无样式 | React Aria | 深度的基础原语层 | 公开文档 |
| **Ark UI** | 无样式 | Zag.js 状态机 | Headless 组件 | 公开文档 |
| **Tremor** | Tailwind CSS v4 | 面向仪表盘的组件 | 数据分析 / 数据展示 | 公开文档 |
| **Park UI** | Panda CSS / Tailwind | Ark UI | 带样式的 Ark 组件 | 公开文档 |
## 1. HeroUI
<DocsImage
src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-og_2x.jpg"
darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-og-black_2x.jpg"
alt="HeroUI - Beautiful by default, customizable by design"
/>
[HeroUI](https://heroui.com) 将 [React Aria](https://react-spectrum.adobe.com/react-aria/) 的可访问性能力与 [Tailwind CSS v4](https://tailwindcss.com/) 样式系统、以及复合组件 API（`Card.Header`、`Table.Column`、`Modal.Body`）结合在一起。组件原生支持 React 19 与 Next.js App Router。
**核心优势：**
- **可访问性优先的架构。** 每个组件都构建在 React Aria 之上 —— Adobe 经过大规模生产验证的可访问性原语。这意味着屏幕阅读器支持、键盘导航和 ARIA 属性都是开箱即用、正确实现的，而不是事后再补上的功能。
- **原生支持 Tailwind CSS v4。** HeroUI 的样式系统采用基于 CSS 的主题方案，通过 `@theme` 与设计 token 实现，避免了 CSS-in-JS 的运行时开销。
- **复合组件 API。** 组件采用可组合的模式（`Card.Header`、`Card.Content`、`Card.Footer`），让你在不牺牲易用性的前提下完全掌控标签结构与布局。
- **AI 工具支持。** HeroUI 提供了 [MCP 服务器](/docs/react/getting-started/mcp-server)、[llms.txt](/docs/react/getting-started/llms-txt) 和 [agent skills](/docs/react/getting-started/agent-skills)，让 AI 编码助手能查到最新的 HeroUI API，而不必只依赖训练数据。
- **对服务端组件友好。** 组件在设计时就考虑了 React Server Components —— 客户端边界精简且文档清晰。
**适用场景：** 你需要一个现代化、可访问性良好的组件库，搭配 Tailwind CSS 样式系统和一流的 AI 工具支持。非常适合使用 Next.js、React 19 与 Tailwind v4 的新项目。
---
## 2. shadcn/ui
[shadcn/ui](https://ui.shadcn.com/) 并不是传统意义上的组件库 —— 它是基于 Radix UI 与 Tailwind CSS 的一组可复制粘贴的组件。你不需要安装某个 npm 包，而是把组件源码直接加入项目。
**核心优势：**
- **完全的所有权。** 组件代码就在你的代码库里，可以随意修改，无需对抗库的抽象，也不必等待上游变更。
- **基于 Radix UI 的可访问性。** 底层原语稳定地处理了弹出层、下拉选择、对话框等复杂交互的可访问性。
- **CLI 工具。** `shadcn` CLI 可以将组件、依赖与文件结构一键脚手架到你的项目中。
- **面向 AI 的文档。** shadcn/ui 同时发布了 `llms.txt`、skills 以及 MCP 服务器，供 AI 代理使用。
- **庞大的生态。** 社区围绕 shadcn 的模式构建了数百个扩展、主题与集成方案。
**适用场景：** 你希望对组件代码拥有最大控制权，并愿意自己维护这些被复制进来的组件。适合需要大量定制化的团队。
**权衡点：** 你拥有代码，也就拥有了 bug。上游的修复和改进都需要手动重新合并，没有集中式的升级机制。此外，shadcn/ui 建立在 Radix UI 之上，存在一定的不确定性 —— 原 Radix 团队已将重心转向 Base UI，Radix 基础组件的长期维护状态在社区中仍是一个悬而未决的问题。
---
## 3. Material UI (MUI)
[Material UI](https://mui.com/) 是最成熟的 React 组件库，已在生产环境中使用了十年。MUI 稳定的样式路径仍然以 Emotion 与 `sx` prop 为核心；Pigment CSS 则作为零运行时的实验性方向存在，并非默认选项。
**核心优势：**
- **组件数量庞大。** 拥有超过 70 个组件，几乎覆盖了你能想到的所有 UI 模式 —— 从基础按钮到复杂的数据网格。
- **遵循 Material Design。** 如果你的设计系统基于 Material Design，MUI 可以提供像素级精准的实现。
- **企业级生态。** MUI X 提供高级组件（数据网格、日期选择器、图表），并附带企业级支持与 SLA。
- **成熟且久经考验。** 数以千计的生产应用运行在 MUI 之上，多年来许多边缘场景都已被发现并修复。
**适用场景：** 你正在构建一个大型企业级应用，需要遵循 Material Design 规范，或者需要使用 MUI X 的高级数据网格和日期选择器组件。
**权衡点：** Material Design 的美学风格非常鲜明。把它改造成完全不同的外观虽然可行，但需要相当大的投入。包体积也比大多数同类方案更大。
---
## 4. Chakra UI
[Chakra UI](https://chakra-ui.com/) 在 React 中率先推广了 "style props" 模式，让你能用 `bg="blue.500"`、`p={4}` 这样的 props 来设置样式。Chakra 当前的主题文档描述了一套围绕 Panda CSS API 构建的体系，包含 `defineConfig`、`createSystem`、recipes、slot recipes、tokens 与语义化 tokens。
**核心优势：**
- **直观的样式 API。** Style props 让你不必离开 JSX，就能快速完成设计的原型与迭代。
- **设计 token 体系。** 通过 theme 对象集中管理颜色、间距、字体和断点。
- **良好的可访问性默认值。** 组件遵循 WAI-ARIA 模式并内置键盘导航支持。
- **基于 recipe 的样式方案。** Chakra 使用 recipe、slot recipe 与基于 token 的体系来组织组件样式。
- **AI 支持。** Chakra 提供了用于 AI 辅助工作流的 MCP 服务器文档。
**适用场景：** 你更喜欢通过 props 而非 class 名来设置样式，并且希望拥有一套默认值统一的设计系统。
**权衡点：** 对于复杂组件，style props 模式会让 JSX 显得比较冗杂。从 v2 升级到 v3 需要较多改动，因为组件与主题 API 都发生了变化。
---
## 5. Mantine
[Mantine](https://mantine.dev/) 是一个功能非常齐全的 React 组件库，组件目录非常宽广，还附带一个 hooks 包以及丰富的扩展生态。Mantine 官网当前将该库描述为提供 `120+` 个组件和 `70+` 个 hooks。
**核心优势：**
- **覆盖面无可匹敌。** Mantine 拥有大量组件和扩展，几乎涵盖各种产品需求 —— 日期选择器、通知、Spotlight 搜索、图表、表单等等。
- **庞大的 hooks 包。** 除了组件之外，Mantine 还提供了 localStorage、媒体查询、剪贴板、空闲检测等大量常用模式的 hooks。
- **基于 CSS 的样式方案。** Mantine 组件基于 CSS 文件构建，可通过 Styles API 进行自定义。
- **AI 工具支持。** Mantine 提供了 LLM 文档、skills 与 MCP 服务器。
- **表单库。** `@mantine/form` 提供了状态管理与校验的能力，可以与 Mantine 输入组件无缝集成。
**适用场景：** 你想要一个开箱即用、包罗万象的库，几乎任何使用场景都能找到对应组件，而无需再引入第三方包。
**权衡点：** 巨大的表面积意味着如果不仔细做 tree-shaking，包体积会迅速膨胀。组件设计风格虽然简洁，但相对鲜明。
---
## 6. Radix UI (Primitives)
[Radix UI](https://www.radix-ui.com/) 提供了一组无样式、可访问的 UI 基础组件，由你自行决定如何赋予样式。它是 shadcn/ui 以及许多其他组件库的底层基础。
**核心优势：**
- **可访问性标杆。** 每个基础组件都按照 WAI-ARIA 规范构建，键盘导航、焦点管理与屏幕阅读器支持都极其完善。
- **默认无样式。** 不预设任何设计立场，也就不必和库的美学风格博弈。把你自己的样式体系带上即可。
- **可组合的 API。** 基础组件采用复合组件模式，通过基于 slot 的组合方式，让你对每一个被渲染的元素都有掌控权。
- **经过生产验证。** 通过直接使用以及 shadcn/ui，Radix 基础组件已经支撑了数千个生产应用。
**适用场景：** 你需要只提供行为、不带样式的可访问基础组件，并希望对样式有完全控制权。非常适合构建定制化设计系统的团队。
**权衡点：** 所有样式都需要自己实现。对于较简单的使用场景，组合模式的学习曲线可能略陡。
---
## 7. Ant Design
[Ant Design](https://ant.design/) 是由蚂蚁集团（阿里巴巴）创建的综合性设计系统与组件库，在企业级应用以及中国开发者社区中尤为流行。
**核心优势：**
- **企业级组件。** Table（支持排序、过滤、分页）、Form（带校验）、Tree 等复杂组件都非常成熟、功能丰富。
- **附带完整的设计系统。** Ant Design 不仅是组件库，还是一套完整的设计系统，包括设计 tokens、模式与规范指南。
- **国际化支持出色。** 一流的 i18n 支持，提供 60+ 个本地化包。
- **组件质量高。** 每个组件都处理了大量边缘情况，你自己实现的话需要花费大量时间。
**适用场景：** 你正在构建复杂的企业级应用，尤其是需要复杂数据表格、表单与树形视图的场景。
**权衡点：** 设计风格非常鲜明的 "Ant Design 范"，要改造成不同的外观需要相当多的工作。包体积较大。可访问性虽然在不断改进，但仍落后于基于 Radix / React Aria 的库。
---
## 8. Headless UI
[Headless UI](https://headlessui.com/) 是 Tailwind Labs 团队提供的一组无样式、可访问的 UI 组件，专注于常见的交互模式 —— 下拉菜单、对话框、Tabs、组合框等。
**核心优势：**
- **与 Tailwind CSS 深度集成。** 出自 Tailwind 团队，与 Tailwind 的工具类与过渡工具配合得天衣无缝。
- **小巧而聚焦。** 仅覆盖那些真正难以做到可访问的组件（菜单、列表框、对话框等）。
- **轻量。** 由于聚焦的组件集合，对包体积的影响极小。
- **简洁的 API。** 使用 render props 和复合组件，API 简单且可预测。
**适用场景：** 你正在使用 Tailwind CSS，需要少量可访问的交互组件，但不想引入一整套 UI 库。
**权衡点：** 组件集合非常小 —— 数据表格、表单输入、日期选择器等大多数模式都需要另寻他解。
---
## 9. React Aria (Primitives)
[React Aria](https://react-spectrum.adobe.com/react-aria/) 是 Adobe 出品的 React 可访问性原语库。它提供 hooks 与组件，帮助你从零构建可访问的 UI。
**核心优势：**
- **业界领先的可访问性。** React Aria 可以说是目前可用的最完善的可访问性原语库。它处理了国际化、从右到左布局、触摸交互，以及大多数库都会忽略的边缘情况。
- **Hooks + 组件。** 同时提供低层 hooks（最大灵活性）与高层组件（更便捷）。
- **平台感知。** 根据设备类型、指针类型与平台惯例自动调整行为。
- **众多库的底层基础。** HeroUI、Adobe Spectrum 以及其他库都建立在 React Aria 之上，证明了它在大规模场景下的可靠性。
**适用场景：** 你正在从零构建设计系统，需要尽可能强大的可访问性基础。当你需要特定基础组件（例如颜色选择器或日历）而其他库无法提供时，它也很有用。
**权衡点：** 比带样式的库学习曲线更陡。你需要自行实现所有样式与组合模式。
---
## 10. Ark UI
[Ark UI](https://ark-ui.com/) 出自 Chakra UI 的作者团队，是一个 headless 组件库，底层基于状态机，行为高度可预测。
**核心优势：**
- **状态机架构。** 底层使用 Zag.js 状态机，组件行为可预测、易于调试。
- **框架无关的内核。** 同一套状态机驱动每个组件的 React、Vue 与 Solid 版本。
- **现代模式。** 提供了签名板、Pin 输入框、分栏器等其他 headless 库中较少见的组件。
- **样式方案灵活。** 可搭配任何样式方案 —— Tailwind、Panda CSS、原生 CSS、CSS Modules 都行。
**适用场景：** 你想要带可预测状态管理的 headless 组件，或者需要在 React、Vue 与 Solid 项目之间复用组件逻辑。
**权衡点：** 社区规模小于 Radix 或 React Aria。状态机抽象在简单组件上会带来额外的概念负担。
---
## 11. Tremor
[Tremor](https://tremor.so/) 专注于仪表盘与数据可视化。其当前文档显示 Tremor Raw 面向 React 18.2+ 与 Tailwind CSS 4.0+ 设计。
**核心优势：**
- **以仪表盘为中心。** 针对数据分析、仪表盘 UI 与数据展示提供专门的资源。
- **Tailwind 原生。** 无需额外样式配置，即可与现有 Tailwind 项目无缝集成。
- **简洁的默认样式。** 图表与指标卡开箱即用，外观精致、设计语言统一。
- **聚焦的范围。** 只关注数据展示，可以按需取用，而不必引入整套 UI 框架。
**适用场景：** 你正在构建数据分析仪表盘或数据密集型界面，并已经在使用 Tailwind CSS。
**权衡点：** 仅限于仪表盘相关组件。对于表单、导航、对话框等通用 UI 模式，你需要另寻他库。
---
## 12. Park UI
[Park UI](https://park-ui.com/) 是构建在 Ark UI 基础组件之上的带样式组件库，提供 Panda CSS 与 Tailwind CSS 两种版本。
**核心优势：**
- **预先样式化的 Ark UI。** 在 Ark UI 的 headless 组件基础上叠加了精致、可定制的样式 —— 类似 shadcn/ui 对 Radix 的做法。
- **支持双样式方案。** 提供 Panda CSS 与 Tailwind CSS 两种变体，按项目情况选择即可。
- **复制粘贴模式。** 与 shadcn/ui 一样，组件以源码形式加入你的项目，你拥有它们并可自由定制。
- **设计 tokens。** 自带 token 体系，可以方便地进行全局样式调整。
**适用场景：** 你喜欢 shadcn/ui 的复制粘贴模式，但更倾向于使用基于状态机的 Ark UI 而非 Radix，或者你正在使用 Panda CSS。
**权衡点：** 相比 shadcn/ui，社区与生态规模更小，第三方扩展和主题也较少。
---
## 如何选择
并不存在一个绝对"最好"的库 —— 正确的选择取决于你项目的约束条件：
- **使用 Tailwind v4 开始新项目？** HeroUI 提供了最现代的技术栈：React Aria 可访问性、复合组件以及 AI 工具支持。
- **想完全拥有组件代码？** shadcn/ui 或 Park UI 让你直接把组件复制进项目。
- **构建有复杂数据需求的企业级应用？** MUI 的数据网格或 Ant Design 的表格组件难以被超越。
- **需要最强的可访问性合规？** HeroUI 基于 React Aria 的底层提供了开箱即用的最强可访问性。
- **希望拥有一套高质量的通用 UI 工具箱？** HeroUI 覆盖了所有核心 UI 模式并具备深度的可访问性；对于富文本编辑器等特定需求，可以搭配专门的库一起使用。
- **跨多个框架工作？** Ark UI 的状态机可以同时在 React、Vue 与 Solid 中使用。
## 开始使用 HeroUI
如果你正在启动一个新的 React 项目，希望使用可访问性良好、设计精美、基于 Tailwind CSS v4 的组件，那么不妨试试 HeroUI：
- [快速开始指南](/docs/react/getting-started/quick-start)
- [组件文档](/docs/react/components)
- [GitHub 仓库](https://github.com/heroui-inc/heroui)
- [Discord 社区](https://discord.gg/heroui)
apps/docs/content/blog/cn/why-choose-heroui-for-your-design-system.mdx
+305
View File
@@ -0,0 +1,305 @@
---
title: "为什么选择 HeroUI 作为你的设计系统"
description: "为什么选择 HeroUI：基于 React Aria 的可访问性、Tailwind CSS v4 样式系统、复合组件以及面向生产级 React 应用的 AI 原生工具支持。"
date: "2026-05-17"
author: "Junior Garcia"
authorHandle: "@jrgarciadev"
authorUrl: "https://x.com/jrgarciadev"
authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4"
tags: ["heroui", "design-system", "react", "ui-libraries"]
image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-og_2x.jpg"
darkImage: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-og-black_2x.jpg"
---
大多数 React 组件库都在解决同一个问题：不再重复造按钮。但设计系统往往会在另一个阶段出问题 —— 当你选用的库无法灵活贴合产品需求时；当可访问性是发布之后才匆忙补上的考量时；又或者当你的 AI 编码助手凭空臆造出根本不存在的 props 时。
HeroUI 将 [React Aria](https://react-spectrum.adobe.com/react-aria/) 的可访问性、[Tailwind CSS v4](https://tailwindcss.com/) 的样式系统，以及一套复合组件 API 结合到一起 —— 让你拥有结构上的掌控权，又不必让 props 数量失控。本文将给出选择它作为设计系统基础的具体理由。
## 技术栈
| 分层 | 技术 | 原因 |
|-------|-----------|-----|
| **可访问性** | React Aria (Adobe) | 业界领先的 WCAG 基础原语，由 Adobe 积极维护 |
| **样式** | Tailwind CSS v4 | 静态 CSS、零运行时、通过 `@theme` 定义设计 tokens |
| **组件 API** | 复合组件 | `Card.Header`、`Modal.Body` —— 结构可控，不必让 props 失控 |
| **类型** | TypeScript | 完整类型覆盖、泛型 props、兼容严格模式 |
| **AI 工具** | MCP 服务器、llms.txt、agent skills | 让 AI 助手能拿到最新 API，而非陈旧的训练数据 |
| **跨平台** | HeroUI Native (React Native) | 同一套设计系统覆盖 Web 与移动端 —— 目前没有其他开源库能做到这一点 |
## 真正达到企业级标准的可访问性
每个 HeroUI 组件都构建在 [React Aria](https://react-spectrum.adobe.com/react-aria/) 之上 —— Adobe 的可访问性原语库。这不是营销话术：React 生态中没有比它更深入的可访问性基础，它甚至支撑着 Adobe 自己的生产级设计系统（Spectrum），覆盖 Photoshop Web、Acrobat 和 Lightroom 等产品。
React Aria 处理了大多数库都未顾及的部分：
- **感知平台的键盘导航。** Mac、Windows 与 Linux 在 Home/End、option/alt+方向键和焦点行为上有着不同的惯例。React Aria 会自动适配。
- **屏幕阅读器的播报。** 实时区域、状态消息以及动态内容播报，在 JAWS、NVDA 和 VoiceOver 上都能正确工作。
- **触摸交互。** 移动端的长按、拖放与手势处理 —— 不仅仅是点击事件。
- **国际化。** 从右到左布局、按区域格式化日期/数字，以及对 30+ 种语言的字符串排序支持。
- **虚拟焦点。** 对于包含成千上万项的集合，React Aria 在保持性能的同时仍能正确通知屏幕阅读器。
这些都很重要，因为在 2026 年，可访问性合规已经不再是可选项。政府、医疗、金融与教育行业都要求符合 WCAG。HeroUI 把这种合规作为默认能力提供，而不是需要额外升级才能获得的特性。
### React Aria 与 Radix UI 的对比
许多流行的库（如 shadcn/ui、Park UI）都构建在 Radix UI 之上。Radix 本身很扎实，但原团队已将重心转向 Base UI，Radix 基础组件的长期维护仍是未定之数。React Aria 则由 Adobe 持续维护 —— 一家自身产品就严重依赖它的公司。
## 原生支持 Tailwind CSS v4
HeroUI 不是把 Tailwind 当作兼容层 —— 它从一开始就是为 Tailwind CSS v4 设计的。
**这意味着：**
- **零运行时 CSS 开销。** 所有样式都是静态 CSS，在构建时就被解析完毕。没有 CSS-in-JS 的运行时计算，没有样式注入，也没有水合(hydration)成本。
- **通过 CSS 自定义属性定义设计 tokens。** 主题以标准 CSS `@theme` 指令的形式存在，而不是 JavaScript 配置对象。改一个 token，所有组件随之更新。
- **基于工具类的自定义。** 用 `className` 覆盖任意组件 —— 与你在项目其他地方使用 Tailwind 的方式完全一致。
- **更小的输出体积。** Tailwind v4 的新引擎生成的 CSS 更少，再加上 HeroUI 的模块化导入，能让你的生产环境包保持精简。
```tsx
<Button variant="secondary" className="font-semibold tracking-wide">
Get Started
</Button>
<Card className="max-w-md shadow-lg">
<Card.Header className="pb-0">
<Card.Title className="text-xl font-bold">Dashboard</Card.Title>
</Card.Header>
<Card.Content className="py-4">
Your metrics here
</Card.Content>
</Card>
```
如果你的团队已经在用 Tailwind，引入 HeroUI 不会带来第二套样式系统。如果你还没用 Tailwind，是否采用它是另一个独立的决定 —— 但这是 2026 年大多数 React 团队都已经做出的选择。
## 复合组件 API
HeroUI 采用复合组件 —— 父组件通过点号语法暴露其子组件的模式。这与 Radix UI 的做法相同，并且在复杂 UI 上比基于 props 的 API 扩展性更好。
```tsx
<Modal>
<Button>Open</Button>
<Modal.Backdrop>
<Modal.Container>
<Modal.Dialog>
<Modal.Header>
<Modal.Heading>Confirm</Modal.Heading>
</Modal.Header>
<Modal.Body>Are you sure?</Modal.Body>
<Modal.Footer>
<Button variant="ghost">Cancel</Button>
<Button>Confirm</Button>
</Modal.Footer>
</Modal.Dialog>
</Modal.Container>
</Modal.Backdrop>
</Modal>
```
**这种模式对设计系统的意义：**
- **结构可控。** 可以在组件的各个部分之间重新排列、省略或插入自定义元素，而不必与库的内部布局对抗。
- **细粒度的样式。** 可以为任意子组件单独应用 `className`，让 `Card.Header` 与 `Card.Footer` 拥有不同样式，无需 CSS 覆盖。
- **TypeScript 校验。** 编译器会检查你的组件树结构 —— 错误嵌套在构建时就会被发现，而不是带到生产环境。
- **JSX 可读性强。** 组件的层级结构直接映射到 UI 的视觉层级。新成员阅读代码即可理解布局。
## <ComponentCount />+ 个组件
HeroUI 提供 <ComponentCount />+ 个组件，以及 <ExampleCount />+ 个有文档的示例。库覆盖了产品 UI 的完整面：
- **数据输入** —— Input、Textarea、NumberField、Select、ComboBox、Autocomplete、DatePicker、DateRangePicker、ColorPicker、Slider、Switch、Checkbox、Radio
- **数据展示** —— Table（排序、选择、分页）、Avatar、Badge、Chip、Tag、Skeleton
- **布局** —— Card、Surface、Separator、Fieldset
- **导航** —— Tabs、Breadcrumbs、Pagination、Link
- **反馈** —— Toast、ProgressBar、ProgressCircle、Meter、Spinner
- **覆盖层** —— Modal、Drawer、Popover、Tooltip、Dropdown、AlertDialog
- **展开/折叠** —— Accordion、Disclosure
- **动作类** —— Button、ToggleButton、ToggleButtonGroup
像 Calendar、DatePicker、ColorPicker 和 Table 这样的复杂组件都是自包含的 —— 它们在内部处理日期运算、本地化格式、键盘导航以及屏幕阅读器播报。这些组件想做到真正可访问其实非常困难，而 HeroUI 把它们作为持续维护、经过测试的原语提供出来。
## 面向 AI 的原生工具
如今，绝大多数开发者每天都在使用 AI 编码助手。生成代码的质量取决于 AI 是否拥有你所用组件库的准确上下文 —— 否则就只能凭借陈旧的训练数据猜测。
HeroUI 提供了四项官方集成：
### MCP 服务器
一个 [Model Context Protocol 服务器](/docs/react/getting-started/mcp-server)，AI 代理可以通过它查询组件文档、API、源码与设计 tokens。可接入 Cursor、Claude Code、Windsurf，或任何兼容 MCP 的编辑器。
当 AI 助手能够访问 MCP 服务器时，它可以查到任意 HeroUI 组件的复合组件结构、可用 props 以及正确的 import —— 不再需要凭空臆造。
[了解如何配置 MCP 服务器 →](/docs/react/getting-started/mcp-server)
### llms.txt
一个结构化参考文件，位于 [heroui.com/llms.txt](/docs/react/getting-started/llms-txt)，为 LLM 提供整个库的精炼且准确的参考。这是一个标准化格式，AI 工具会读取它来避免生成已废弃的写法。
[进一步了解 llms.txt →](/docs/react/getting-started/llms-txt)
### Agent Skills
为 Cursor、Claude Code 等 AI 工具预构建的 [skill 文件](/docs/react/getting-started/agent-skills)，帮助 AI 代理掌握 HeroUI 的约定 —— 包括正确的 import、复合组件模式、样式方案以及项目脚手架。
[了解如何安装 Agent Skills →](/docs/react/getting-started/agent-skills)
### AGENTS.md
一份 [AGENTS.md 文件](/docs/react/getting-started/agents-md)，为 AI 编码代理提供仓库级上下文。它描述了项目结构、编码约定与组件模式，让代理从第一次 prompt 起就理解你的代码库。
[了解 AGENTS.md →](/docs/react/getting-started/agents-md)
**结果是：** AI 助手能够生成正确的 HeroUI v3 代码，使用正确的复合组件模式、import 路径与 Tailwind 类名。这一点至关重要，因为错误的 AI 输出在调试上耗费的时间，远多于它生成代码本身节省的时间。
## 生态系统
### HeroUI Pro
[HeroUI Pro](https://heroui.com/pro) 在基础库之上扩展了应用级组件与模板：
- **AppLayout、Sidebar、Navbar** —— 包含响应式行为的完整应用外壳
- **DataGrid** —— 支持类型化列、排序与过滤的高密度数据表格
- **KPI、NumberValue、TrendChip** —— 仪表盘指标组件
- **LineChart、BarChart** —— 数据可视化
- **Sheet、CommandMenu** —— 高级覆盖层模式
- **模板** —— 仪表盘、财务、聊天与邮件应用等起点模板
Pro 是付费产品 —— 当你需要的不仅是 UI 组件，更是应用级基础设施时再使用。
### HeroUI Native
<DocsImage
src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/heroui-native-og-light-1.webp"
darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/heroui-native-og-dark-1.webp"
alt="HeroUI Native - React Native components"
/>
HeroUI 是目前唯一在 Web 与移动端上都能提供同等组件质量的开源设计系统。[HeroUI Native](/docs/native/getting-started) 把同一套设计 tokens、复合组件 API 以及可访问性标准带到 React Native —— 利用各平台的原生 API，而非简单地包装 WebView。
这意味着构建跨平台产品的团队可以在 React（Web）和 React Native（移动端）之间共享同一套设计系统，无需对任何一端妥协。统一的视觉语言、统一的组件模式、统一的主题 tokens —— 但在各端都使用原生渲染。
目前没有其他开源 React 组件库能够做到这一点。MUI、shadcn/ui、Chakra UI 与 Mantine 都仅限于 Web。如果你的产品需要同时支撑 Web 与移动端，HeroUI 是唯一一套能从同一基础覆盖两端的设计系统。
### Figma Kit
<DocsImage
src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/blog/community-figma-preview-light.png"
darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/blog/community-figma-preview-dark.png"
alt="HeroUI Figma Kit"
/>
[HeroUI Figma Kit (v3)](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3) 让设计与代码保持同步。Figma 中的组件与 React 实现一一对应，设计师与开发者基于同一份真实来源进行工作。
### Storybook
每个组件都有对应的 [Storybook stories](https://storybook-v3.heroui.com/)，展示所有变体、状态与组合方式。可用于可视化测试、设计评审与文档。
### 社区
HeroUI 并非新生事物 —— 我们已经构建了 5 年多，最早从 v1（最初的 NextUI）开始。社区规模稳步增长：GitHub 上有 29.3K+ stars，Discord 上有 9K+ 成员，每周还有数以千计的讨论、社区回答与 issue 被解决。
- [GitHub](https://github.com/heroui-inc/heroui) —— 源码、issue 与讨论
- [Discord](https://discord.gg/heroui) —— 9K+ 成员，社区支持与公告
- [X / Twitter](https://x.com/hero_ui) —— 更新与版本发布
### 获得 Y Combinator 投资
HeroUI 获得了风险投资，包括 [Y Combinator](https://www.ycombinator.com/companies/heroui)。这意味着我们有专职的全职团队、长期的维护承诺，以及持续交付所需的资源。在选用一个组件库时，你其实是在押注它的未来 —— HeroUI 的目标是长期存在。
## 开箱即用的设计品质
HeroUI 提供经过精心打磨的默认样式，不做任何主题定制看起来也很精致：
- **流畅的动画。** 按钮带有细腻的按下反馈，弹窗以弹簧物理动效呈现，手风琴展开时使用自然的缓动曲线。
- **均衡的间距 tokens。** 所有组件遵循统一的数学比例，padding、margin 与 gap 都保持一致。
- **阴影层级。** 浅色与深色模式下都能良好工作的高度层级，无需手动调整。
- **主题变体。** 内置 glass、brutalism 以及中性等多种视觉风格，通过设计 tokens 即可切换。
设计 token 体系基于 CSS 自定义属性，主题就是标准 CSS：
```css
@theme {
--color-primary: oklch(0.6 0.25 260);
--radius-field: 0.5rem;
--shadow-surface: 0 1px 3px rgba(0, 0, 0, 0.08);
}
```
修改 tokens，所有组件都会随之全局更新。不需要 JavaScript 主题对象，不需要 provider 包装，也没有运行时开销。
想要几次点击就把 HeroUI 变成你自己的样子？[主题构建器](/themes)允许你以可视化的方式自定义颜色、字体、圆角与间距 —— 然后导出一份可直接用于项目的 CSS 主题。
## 两步即可就绪
大多数组件库在渲染第一个组件之前，都需要配置文件、provider 包装、主题对象与插件设置。HeroUI 不需要。整个安装过程只有两步：
**1. 安装：**
```bash
npm i @heroui/styles @heroui/react
```
**2. 在你的 CSS 中加一行：**
```css
@import "tailwindcss";
@import "@heroui/styles"; /* 就这些 */
```
接下来即可使用任意组件 —— 不需要 `ThemeProvider`、不需要 `ChakraProvider`、不需要 `MantineProvider`，也不需要任何配置对象：
```tsx
import { Button, Card } from "@heroui/react";
export default function Page() {
return (
<Card>
<Card.Content>
<Button>Click me</Button>
</Card.Content>
</Card>
);
}
```
整个配置就是这些。不需要用 provider 包裹整个应用，不需要主题配置文件，也不需要任何运行时初始化。安装、引入一行 CSS，然后就可以开始构建。查看[快速开始指南](/docs/react/getting-started/quick-start)，五分钟内即可上手。
## 服务端组件
HeroUI 的设计契合 React Server Components 的模型：
- **静态组件**（`Card`、`Badge`、`Text`、`Separator`、`Avatar`）可以留在服务端组件树中，不带任何客户端 JavaScript。
- **交互式组件**（`Button`、`Modal`、`Table`、`Select`）使用客户端边界 —— 每个组件都有清晰的文档说明。
- **不强制使用 provider** —— 没有迫使整个组件树进入客户端边界的客户端 context。
这意味着你的页面默认会输出更少的 JavaScript。静态布局在服务端渲染，交互式部件仅在需要的位置进行水合(hydration)。
## 一些权衡
HeroUI 采用聚焦的策略：与其交付所有可能的组件，我们更优先保证团队最常使用组件的深度、可访问性与品质。对于富文本编辑、拖放或图表等专门需求，我们建议将 HeroUI 与擅长这些特定问题的专业库搭配使用 —— 这比依赖单一库覆盖所有场景效果更好。
HeroUI 是为 Tailwind CSS v4 构建的。如果你的团队已经在使用 Tailwind，引入它非常顺畅。如果你使用的是其他样式方案，迁移到 Tailwind 是一个独立但值得的投入 —— 那是面向现代 CSS 工具链的一笔投资。
## 谁适合使用 HeroUI
如果你正在构建以下产品，HeroUI 会是个不错的选择：
- **SaaS 应用** —— 表单、表格、覆盖层与导航，并具备 React Aria 的可访问性
- **仪表盘与管理后台** —— 借助 HeroUI Pro 组件构建的高密度数据布局
- **电商门店** —— 高性能、可访问、对 SEO 友好的组件渲染
- **营销官网与落地页** —— 精致的默认样式，没有运行时 CSS 开销
- **跨平台产品** —— 借助 HeroUI Native，在 Web（React）与移动端（React Native）上共享同一套设计系统
- **任何重视可访问性、Tailwind CSS 集成与 AI 辅助开发的 React / Next.js 项目**
## 开始使用
```bash
npm install @heroui/styles @heroui/react
```
- [快速开始指南](/docs/react/getting-started/quick-start) —— 五分钟内即可完成配置
- [组件文档](/docs/react/components) —— 完整的 API 参考与在线示例
- [主题指南](/docs/react/getting-started/theming) —— 自定义设计系统
- [MCP 服务器](/docs/react/getting-started/mcp-server) —— 接入你的 AI 编码助手
- [GitHub 仓库](https://github.com/heroui-inc/heroui) —— 源码与 issue
apps/docs/content/blog/en/best-react-dashboards.mdx
+427
View File
@@ -0,0 +1,427 @@
---
title: "14 Dashboard Templates and Frameworks for React Teams in 2026"
description: "React dashboard templates, admin frameworks, and UI starting points for building admin panels, analytics dashboards, and data-driven applications."
date: "2026-05-10"
author: "Junior Garcia"
authorHandle: "@jrgarciadev"
authorUrl: "https://x.com/jrgarciadev"
authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4"
tags: ["react", "dashboards", "templates"]
image: "/images/blog/best-react-dashboards.jpg"
draft: true
---
Building a React dashboard from scratch takes weeks — picking the right template, framework, or component stack can cut that down dramatically. The strongest options give you responsive layouts, data visualization patterns, accessible navigation, and a theme system you can actually maintain.
I pulled together 14 options worth checking in 2026. Pricing and feature gates change often, so use this as a shortlist and verify the current license before you buy or build on top of anything.
## Quick Comparison
| Template / Framework | Type | Best reason to consider it |
|---------------------|------|----------------------------|
| **HeroUI Pro Dashboard** | Template + Pro components | HeroUI-native app shell, sidebar, navbar, KPI, data grid, and chart patterns |
| **Tremor** | Dashboard UI resources | Tailwind v4 dashboard blocks and analytics-oriented UI |
| **Refine** | Framework | Data-provider driven CRUD/admin applications |
| **AdminJS** | Framework | Generated admin panels from backend models |
| **React Admin** | Framework | Mature admin framework with a large data-provider ecosystem |
| **Ant Design Pro** | Template/framework ecosystem | Ant Design and ProComponents-based admin apps |
| **CoreUI** | Template | Cross-framework admin template ecosystem |
| **Tabler** | Template | Bootstrap-based dashboard UI |
| **Argon Dashboard** | Template | Creative Tim dashboard aesthetic |
| **Material Dashboard** | Template | MUI / Material Design dashboard starting point |
| **Berry** | Template | MUI-based admin dashboard ecosystem |
| **Mantis** | Template | MUI-based admin dashboard ecosystem |
| **shadcn/ui Dashboard** | Example | Source-owned Tailwind dashboard example |
| **HeroUI Pro + custom widgets** | Pro components + template | Start from Pro layout/table/chart primitives, then add product-specific widgets |
---
## 1. HeroUI Pro Dashboard Template
[HeroUI Pro](https://heroui.com/pro) offers pre-built dashboard templates designed specifically for SaaS products, admin panels, and analytics dashboards. Built on HeroUI v3 components with Tailwind CSS v4.
**What you get:**
- Complete dashboard layouts with sidebar navigation, header, and content areas
- Analytics pages with charts, metrics cards, and data tables
- Settings, analytics, orders, tracker, help, finance, chat, and email-style app surfaces across the current templates
- App shell patterns using `AppLayout`, `Sidebar`, and `Navbar`
- Pro dashboard widgets using `KPI`, `DataGrid`, `LineChart`, `NumberValue`, and `TrendChip`
- Dark mode support with HeroUI's theming system
- Responsive design that works on mobile and desktop
**Key strengths:**
- **Production-quality components.** Every component is built on React Aria with full accessibility support and keyboard navigation.
- **Tailwind CSS v4.** Modern styling with CSS-based theming, no runtime overhead.
- **Next.js App Router ready.** Templates are built for the latest Next.js with server components and streaming.
- **AI tooling.** Use HeroUI's MCP server with Cursor or other AI tools to extend and customize dashboards with AI assistance.
**Pricing:** Premium license through HeroUI Pro; check the current pricing page for details.
**Best for:** Teams building SaaS products who want accessible, modern dashboard components they can customize with Tailwind CSS.
---
## 2. Tremor
[Tremor](https://tremor.so/) is focused on dashboard UI. Its current docs describe Tremor Raw as designed for React 18.2+ and Tailwind CSS 4.0+.
**What you get:**
- Dashboard-oriented UI resources
- Tremor Blocks for copy-paste dashboard sections
- Figma UI Kit for dashboard design work
- Tailwind CSS v4 setup guides
**Key strengths:**
- **Dashboard-first design.** The project is centered on analytics and dashboard interfaces.
- **Tailwind native.** Current docs target Tailwind CSS v4.
- **Useful design resources.** The docs link to Tremor Blocks and a Figma UI Kit.
**Trade-offs:** Limited to dashboard-specific components. You'll need another library for forms, navigation, and other general UI patterns.
**Pricing:** Check Tremor's current site and repository before choosing it for a commercial project.
**Best for:** Teams that already have a UI library and need dashboard-specific visualization components to complement it.
---
## 3. Refine
[Refine](https://refine.dev/) is a meta-framework for building data-intensive applications — admin panels, dashboards, and internal tools. It's not a template; it's a framework that generates CRUD interfaces from your data model.
**What you get:**
- Automatic CRUD operations from data provider configuration
- Authentication and authorization hooks
- Routing integration (Next.js, Remix, React Router)
- Connectors for REST, GraphQL, Supabase, Strapi, Appwrite, and more
- UI framework adapters for Ant Design, MUI, Mantine, and Chakra UI
**Key strengths:**
- **Data-first architecture.** Define your data providers and Refine generates the boilerplate — list pages, create/edit forms, show views, and filters.
- **Framework-agnostic UI.** Swap between Ant Design, MUI, Mantine, or Chakra UI without changing your business logic.
- **Headless mode.** Use your own components if none of the bundled UI adapters fit.
- **Active community.** Regular releases, good documentation, and a responsive maintainer team.
**Trade-offs:** The abstraction adds complexity for simple dashboards. If your data layer doesn't fit Refine's provider model, you'll fight the framework more than benefit from it.
**Pricing:** Check Refine's current open-source and commercial offering before choosing it.
**Best for:** Teams building admin panels or internal tools with standard CRUD patterns over existing APIs.
---
## 4. AdminJS
[AdminJS](https://adminjs.co/) (formerly Admin Bro) auto-generates an admin panel from your database models. Point it at your ORM, and it creates a full CRUD interface.
**What you get:**
- Auto-generated admin panel from Sequelize, TypeORM, Mongoose, Prisma, or MikroORM models
- CRUD views, search, filtering, and bulk actions
- Dashboard page with customizable widgets
- Role-based access control
- Custom action hooks for business logic
**Key strengths:**
- **Zero-config setup for common ORMs.** If you use Prisma or TypeORM, AdminJS reads your schema and generates an admin panel automatically.
- **Customizable.** Override components, actions, and views when the defaults don't fit.
- **Plugin system.** Add features like file upload, import/export, and logging through plugins.
**Trade-offs:** The auto-generated UI looks functional but plain. Heavy customization can become painful because you're working against the generated output. The React version uses older patterns.
**Pricing:** Check AdminJS's current open-source and hosted offering before choosing it.
**Best for:** Backend teams that need a quick admin panel for database management without building frontend code.
---
## 5. React Admin
[React Admin](https://marmelab.com/react-admin/) is the most mature admin framework in the React ecosystem, maintained by Marmelab since 2016.
**What you get:**
- Complete admin panel framework with routing, layout, and state management
- List, Create, Edit, Show views with declarative configuration
- Many data provider adapters for common backend patterns
- Authentication hooks and access control
- Theming through MUI
**Key strengths:**
- **Mature and battle-tested.** Years of production use mean many admin edge cases are documented and handled.
- **Declarative API.** Define resources, list columns, form fields, and filters with JSX — React Admin generates the plumbing.
- **Enormous data provider ecosystem.** If your backend speaks a protocol, there's probably a React Admin data provider for it.
- **Enterprise edition.** Calendar, kanban, audit log, real-time updates, and multi-tenancy for teams that need them.
**Trade-offs:** Tightly coupled to MUI for styling. The declarative API is powerful but opaque — debugging what goes wrong inside the framework requires understanding its internals.
**Pricing:** Check React Admin's current licensing and Enterprise Edition details.
**Best for:** Teams building full-featured admin panels that need a mature, well-documented framework with extensive data provider support.
---
## 6. Ant Design Pro
[Ant Design Pro](https://pro.ant.design/) is the official dashboard template ecosystem for Ant Design. It is aimed at full-featured admin products built around Ant Design and ProComponents.
**What you get:**
- Complete admin layout with sidebar, header, and breadcrumbs
- Pre-built pages: dashboard, forms, tables, profiles, error pages
- Authentication and authorization patterns in the Ant Design Pro ecosystem
- ProComponents (ProTable, ProForm, ProLayout) for complex data patterns
- Internationalization with 10+ language packs
**Key strengths:**
- **ProComponents.** Advanced components like ProTable (configurable data table with search, filtering, and actions) save weeks of development time.
- **Umi integration.** Built on the Umi framework with conventions for routing, plugins, and data fetching.
- **Comprehensive template.** Nearly every page you'd need in an admin panel is included and customizable.
**Trade-offs:** Tightly coupled to the Ant Design ecosystem (Umi, Ant Design, AntV). The aesthetic is distinctly Ant Design — theming it to look different is difficult. Documentation is primarily in Chinese with English translations.
**Pricing:** Check Ant Design Pro's current license and repository before choosing it.
**Best for:** Teams already using Ant Design who need a comprehensive admin template with advanced data components.
---
## 7. CoreUI
[CoreUI](https://coreui.io/) is a cross-framework admin template available for React, Vue, Angular, and vanilla Bootstrap. The React version ships with a complete dashboard layout and component set.
**What you get:**
- Dashboard layout with sidebar navigation and header
- 30+ page templates (analytics, user management, settings, etc.)
- Custom UI components built on Bootstrap foundations
- Chart examples for data visualization
- Icon library with 1,500+ icons
**Key strengths:**
- **Cross-framework consistency.** If your organization uses multiple frontend frameworks, CoreUI provides a consistent design language across all of them.
- **Extensive page templates.** Pre-built pages for common admin patterns save time on layout and structure.
- **Regular updates.** Actively maintained with frequent releases.
**Trade-offs:** The Bootstrap foundation feels dated compared to Tailwind-based alternatives. The free version is limited — most useful features require the Pro license.
**Pricing:** Check CoreUI's current pricing and license before choosing it.
**Best for:** Organizations that need the same admin panel design across React, Vue, and Angular projects.
---
## 8. Tabler
[Tabler](https://tabler.io/) is a free, open-source dashboard template built on Bootstrap with a React adaptation. Known for its clean, minimal design and extensive component set.
**What you get:**
- 200+ responsive UI components
- Dashboard layout with multiple navigation patterns
- Apache ECharts integration for data visualization
- Form components with validation
- Email and e-commerce page templates
**Key strengths:**
- **Beautiful design.** Tabler has one of the cleanest default aesthetics of any free dashboard template.
- **Component breadth.** Over 200 components covering navigation, forms, data display, feedback, and layout.
- **Open-source starting point.** Check the current repository license and docs before adopting it.
- **Active development.** Regular releases with new components and improvements.
**Trade-offs:** The React version lags behind the HTML/Bootstrap version in features. TypeScript support is incomplete. Based on Bootstrap rather than a modern CSS approach.
**Pricing:** Check Tabler's current license and template docs before choosing it.
**Best for:** Developers who want a beautiful, free dashboard template and are comfortable with Bootstrap-based styling.
---
## 9. Argon Dashboard
[Argon Dashboard React](https://www.creative-tim.com/product/argon-dashboard-react) by Creative Tim is a popular dashboard template with a distinctive visual style.
**What you get:**
- Dashboard layout with sidebar and navbar
- Pre-built pages (dashboard, maps, tables, user profile)
- Bootstrap-based styling with custom extensions
- Chart examples
**Key strengths:**
- **Distinctive design.** Argon has a recognizable gradient-heavy aesthetic that stands out from more neutral templates.
- **Creative Tim ecosystem.** Integrates with Creative Tim's other products (login pages, landing pages, design system).
- **Good documentation.** Clear setup instructions and component guides.
**Trade-offs:** The free version is bare-bones — most useful pages and components require the Pro license. The design is polarizing. Bootstrap foundation limits modern CSS usage.
**Pricing:** Check Creative Tim's current pricing and license before choosing it.
**Best for:** Teams that like Creative Tim's design aesthetic and want a quick starting point for a dashboard.
---
## 10. Material Dashboard
[Material Dashboard React](https://www.creative-tim.com/product/material-dashboard-react) is another Creative Tim template, built on MUI with a Material Design aesthetic.
**What you get:**
- MUI-based dashboard layout
- Pre-built pages with Material Design styling
- Chart examples for data visualization
- Dark mode support
- RTL layout support
**Key strengths:**
- **Material Design compliance.** If you need a dashboard that follows Google's Material Design guidelines, this delivers out of the box.
- **MUI foundation.** Access to MUI's full component ecosystem for extending beyond the template's defaults.
- **Well-documented.** Clear guides for customization, theming, and deployment.
**Trade-offs:** Same Creative Tim free-vs-Pro split — the free version is limited. Closely tied to MUI, making it hard to use with other styling approaches.
**Pricing:** Check Creative Tim's current pricing and license before choosing it.
**Best for:** Teams using MUI who want a Material Design dashboard template with ready-made pages.
---
## 11. Berry
[Berry](https://berrydashboard.io/) is an MUI-based admin dashboard template known for its polished design and comprehensive feature set.
**What you get:**
- A large set of page templates and widgets
- Chart examples for data visualization
- Authentication page examples
- Multi-language support
- Light and dark themes with RTL support
**Key strengths:**
- **Feature density.** Berry focuses on a large set of pre-built pages and widgets.
- **Chart-heavy pages.** The template includes polished chart-oriented dashboard pages.
- **Auth examples.** Includes authentication-related page examples.
**Trade-offs:** The Pro version is expensive compared to alternatives. MUI dependency means the same theming constraints apply.
**Pricing:** Check the current Berry pricing and license before choosing it.
**Best for:** Teams that want a feature-rich MUI dashboard with multiple authentication patterns and extensive pre-built pages.
---
## 12. Mantis
[Mantis](https://mantisdashboard.io/) is a React admin dashboard built on MUI, focused on clean design and developer experience.
**What you get:**
- Clean, modern dashboard layout
- Chart examples for data visualization
- Authentication page examples
- Form components with validation
- Widget pages for common dashboard patterns
**Key strengths:**
- **Clean aesthetic.** Mantis has a more restrained, modern design compared to other MUI-based templates.
- **Good code organization.** The project structure follows best practices for scalable React applications.
- **Regular updates.** Actively maintained with consistent releases.
**Trade-offs:** Similar to Berry — MUI dependency, limited free version, Pro pricing.
**Pricing:** Check the current Mantis pricing and license before choosing it.
**Best for:** Teams who want a clean, well-organized MUI dashboard template.
---
## 13. Shadcn Dashboard
The [shadcn/ui Dashboard](https://ui.shadcn.com/examples/dashboard) example demonstrates how to build a full dashboard using shadcn/ui components with Tailwind CSS.
**What you get:**
- Example dashboard layout with sidebar and header
- Data table with sorting, filtering, and pagination
- Charts using Recharts
- Account/authentication page examples
- Settings forms
**Key strengths:**
- **Full code ownership.** Since shadcn/ui components are copied into your project, you have complete control over the dashboard code.
- **Tailwind CSS styling.** Clean, utility-first styling that's easy to customize.
- **Community extensions.** Many developers have built expanded dashboard templates on top of the shadcn example.
**Trade-offs:** It's an example, not a production template. You'll need to build out most pages yourself. The components need manual updates when shadcn releases improvements.
**Pricing:** Check shadcn/ui's current license and docs before choosing it.
**Best for:** Developers who want a Tailwind-based dashboard starting point with full control over the source code.
---
## 14. HeroUI Pro + Custom Widgets
If you want a HeroUI-native dashboard, start with [HeroUI Pro](https://heroui.com/pro) rather than rebuilding the frame from base components. Use the Pro dashboard template for the app shell and add product-specific widgets only where your product needs something unique.
**What you get:**
- `AppLayout`, `Sidebar`, and `Navbar` for the dashboard frame
- `KPI`, `DataGrid`, `LineChart`, `NumberValue`, and `TrendChip` for dashboard UI
- Base HeroUI components for local UI around the Pro primitives
- Full control over your data fetching, permissions, and business logic
**Why this works:**
- **No hand-rolled shell.** The app frame, sidebar, navbar, metrics, tables, and charts already have Pro primitives.
- **Modern stack.** The current dashboard template is built with Next.js and HeroUI Pro components.
- **AI-assisted development.** Use HeroUI's MCP server and docs so agents can extend the dashboard with current APIs.
**How to start:**
1. Start from the HeroUI Pro dashboard template.
2. Keep `AppLayout`, `Sidebar`, `Navbar`, `KPI`, `DataGrid`, and chart components as the foundation.
3. Replace the mock data files with your API, database, or analytics source.
4. Add custom widgets only for product-specific workflows.
**Pricing:** Check HeroUI Pro's current pricing and license before choosing it.
**Best for:** Teams that want a HeroUI-native dashboard without rebuilding dashboard infrastructure from scratch.
---
## How to Choose
Your choice depends on what you value most:
- **Speed to launch:** HeroUI Pro Dashboard or Ant Design Pro give you the most complete starting points.
- **Maximum flexibility:** HeroUI Pro plus custom widgets or the shadcn Dashboard example let you build around your product's exact needs.
- **CRUD-heavy admin panels:** React Admin or Refine auto-generate interfaces from your data model.
- **Enterprise needs:** React Admin Enterprise, MUI X, or Berry Pro offer advanced features with support contracts.
- **Budget-friendly:** Tabler, Tremor, and the shadcn Dashboard example are worth checking when you want an open-source starting point.
## Build Your Dashboard with HeroUI
HeroUI provides the components you need to build modern, accessible dashboards:
- [Component Documentation](/docs/react/components) — Tables, Cards, Navigation, Forms, and more
- [Quick Start Guide](/docs/react/getting-started/quick-start) — Set up a new project in minutes
- [HeroUI Pro](https://heroui.com/pro) — Pre-built dashboard templates and premium components
- [Tutorial: Build a React Dashboard](/blog/build-react-dashboard-with-heroui) — Step-by-step guide
apps/docs/content/blog/en/best-react-ui-component-libraries.mdx
+266
View File
@@ -0,0 +1,266 @@
---
title: "12 Best React UI Component Libraries in 2026"
description: "Compare the 12 best React UI component libraries in 2026: HeroUI, shadcn/ui, MUI, Chakra UI, Mantine, and more. Features, accessibility, and AI tooling."
date: "2026-05-16"
author: "Junior Garcia"
authorHandle: "@jrgarciadev"
authorUrl: "https://x.com/jrgarciadev"
authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4"
tags: ["react", "ui-libraries", "comparison"]
image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/blog/heroui-overview-light.png"
darkImage: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/blog/heorui-overview-dark.png"
---
Choosing the right React UI component library can make or break your development workflow. The best React UI component libraries in 2026 ship accessible, production-ready components that let you focus on building features instead of re-implementing dropdowns for the hundredth time.
I compared 12 libraries across styling, accessibility foundation, breadth, AI workflow, and licensing. Exact component counts and pricing can change quickly, so treat this as a practical field guide and check each project's docs before you commit.
<h2 className="blog-table-heading mt-10 text-xl font-semibold text-muted">Quick Comparison</h2>
| Library | Styling | Accessibility foundation | Breadth | AI workflow |
|---------|---------|--------------------------|---------|-------------|
| **HeroUI** | Tailwind CSS v4 | React Aria | <ComponentCount />+ components, <ExampleCount />+ examples | MCP server, llms.txt, agent skills |
| **shadcn/ui** | Tailwind CSS | Radix UI and other primitives | Official docs list 59 component entries | MCP server, llms.txt, skills |
| **Material UI** | Emotion by default, Pigment CSS integration path | MUI implementation | Very broad core + MUI X | Public docs |
| **Chakra UI** | Panda CSS API-based system | Chakra / Ark UI ecosystem | Broad app component set | MCP server and public docs |
| **Mantine** | CSS files / CSS Modules | Mantine implementation | 120+ components, 70+ hooks | MCP server, llms.txt, skills |
| **Radix UI** | Unstyled | Radix primitives | Focused primitives | Public docs |
| **Ant Design** | CSS-in-JS / token system | Ant Design implementation | Enterprise-heavy | Public docs |
| **Headless UI** | Unstyled | Headless UI primitives | Focused primitives | Public docs |
| **React Aria** | Unstyled | React Aria | Deep primitive layer | Public docs |
| **Ark UI** | Unstyled | Zag.js state machines | Headless components | Public docs |
| **Tremor** | Tailwind CSS v4 | Dashboard-focused components | Analytics/data display | Public docs |
| **Park UI** | Panda CSS / Tailwind | Ark UI | Styled Ark components | Public docs |
## 1. HeroUI
<DocsImage
src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-og_2x.jpg"
darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-og-black_2x.jpg"
alt="HeroUI - Beautiful by default, customizable by design"
/>
[HeroUI](https://heroui.com) pairs [React Aria](https://react-spectrum.adobe.com/react-aria/) accessibility with [Tailwind CSS v4](https://tailwindcss.com/) styling and a compound component API (`Card.Header`, `Table.Column`, `Modal.Body`). Components work with React 19 and the Next.js App Router out of the box.
**Key strengths:**
- **Accessibility-first architecture.** Every component is built on React Aria, Adobe's battle-tested accessibility primitives. This means screen reader support, keyboard navigation, and ARIA attributes are handled correctly out of the box — not bolted on as an afterthought.
- **Tailwind CSS v4 native.** HeroUI's styling system uses CSS-based theming with `@theme` and design tokens, avoiding the runtime overhead of CSS-in-JS.
- **Compound component API.** Components use a composable pattern (`Card.Header`, `Card.Content`, `Card.Footer`) that gives you full control over markup and layout without sacrificing ergonomics.
- **AI tooling.** HeroUI ships an [MCP server](/docs/react/getting-started/mcp-server), [llms.txt](/docs/react/getting-started/llms-txt), and [agent skills](/docs/react/getting-started/agent-skills) so AI coding assistants can look up current HeroUI APIs instead of relying only on training data.
- **Server component friendly.** Components are designed with React Server Components in mind — client boundaries are minimal and clearly documented.
**When to use it:** You want a modern, accessible component library with Tailwind CSS styling and first-class AI tooling support. Ideal for new projects using Next.js, React 19, and Tailwind v4.
---
## 2. shadcn/ui
[shadcn/ui](https://ui.shadcn.com/) isn't a traditional component library — it's a collection of copy-paste components built on Radix UI and Tailwind CSS. Instead of installing a package, you add component source code directly to your project.
**Key strengths:**
- **Full ownership.** Components live in your codebase, so you can modify them freely without fighting library abstractions or waiting for upstream changes.
- **Radix UI foundation.** The underlying primitives handle accessibility and complex interactions (popovers, comboboxes, dialogs) reliably.
- **CLI tooling.** The `shadcn` CLI scaffolds components into your project with the right dependencies and file structure.
- **AI-ready docs.** shadcn/ui publishes `llms.txt`, skills, and an MCP server for agents.
- **Massive ecosystem.** The community has built hundreds of extensions, themes, and integrations around shadcn's patterns.
**When to use it:** You want maximum control over component code and you're comfortable maintaining copied components. Works well for teams that need heavy customization.
**Trade-offs:** You own the code, which means you also own the bugs. Upstream fixes and improvements require manual re-integration. No central update mechanism. Additionally, shadcn/ui's foundation on Radix UI carries some uncertainty — the original Radix team has shifted focus to Base UI, and the long-term maintenance status of Radix primitives is an open question in the community.
---
## 3. Material UI (MUI)
[Material UI](https://mui.com/) is the most established React component library, with a decade of production use. MUI's stable styling path still centers on Emotion and the `sx` prop; Pigment CSS exists as an experimental zero-runtime direction rather than the default.
**Key strengths:**
- **Massive component count.** Over 70 components covering nearly every UI pattern you can think of, from basic buttons to complex data grids.
- **Material Design compliance.** If your design system is built on Material Design, MUI gives you pixel-perfect implementations.
- **Enterprise ecosystem.** MUI X offers premium components (data grid, date pickers, charts) with enterprise support and SLAs.
- **Mature and battle-tested.** Thousands of production apps run on MUI. Edge cases have been found and fixed over years.
**When to use it:** You're building a large enterprise application that needs Material Design compliance, or you need MUI X's premium data grid and date picker components.
**Trade-offs:** The Material Design aesthetic is opinionated. Theming away from Material's look-and-feel is possible but requires significant effort. Bundle size is larger than most alternatives.
---
## 4. Chakra UI
[Chakra UI](https://chakra-ui.com/) pioneered the "style props" pattern in React, letting you style components with props like `bg="blue.500"` and `p={4}`. Chakra's current theming docs describe a system built around the Panda CSS API with `defineConfig`, `createSystem`, recipes, slot recipes, tokens, and semantic tokens.
**Key strengths:**
- **Intuitive styling API.** Style props make it fast to prototype and iterate on designs without leaving your JSX.
- **Design token system.** The theme object gives you centralized control over colors, spacing, fonts, and breakpoints.
- **Good accessibility defaults.** Components follow WAI-ARIA patterns and include keyboard navigation.
- **Recipe-driven styling.** Chakra uses recipes, slot recipes, and a token-based system for component styling.
- **AI support.** Chakra documents an MCP server for AI-assisted workflows.
**When to use it:** You like styling through props rather than class names, and you want a cohesive design system with good defaults.
**Trade-offs:** The style props pattern can make JSX noisy for complex components. Migrating from v2 to v3 required significant changes because the component and theming APIs changed.
---
## 5. Mantine
[Mantine](https://mantine.dev/) is a full-featured React component library with a very broad component catalog, a hooks package, and a rich extension ecosystem. Mantine's homepage currently describes the library as `120+` components and `70+` hooks.
**Key strengths:**
- **Unmatched breadth.** Mantine has components and extensions for many product needs — date pickers, notifications, spotlight search, charts, forms, and more.
- **Large hooks package.** Beyond components, Mantine ships hooks for local storage, media queries, clipboard, idle detection, and many other common patterns.
- **CSS styling.** Mantine components are built with CSS files and can be customized through the Styles API.
- **AI tooling.** Mantine publishes LLM docs, skills, and an MCP server.
- **Form library.** `@mantine/form` provides form state management with validation that integrates seamlessly with Mantine inputs.
**When to use it:** You want a batteries-included library where you can find a component for almost any use case without adding third-party packages.
**Trade-offs:** The huge surface area means the bundle can grow quickly if you're not tree-shaking carefully. The component design aesthetic, while clean, is fairly specific.
---
## 6. Radix UI (Primitives)
[Radix UI](https://www.radix-ui.com/) provides unstyled, accessible UI primitives that you style yourself. It's the foundation behind shadcn/ui and many other component libraries.
**Key strengths:**
- **Accessibility gold standard.** Every primitive is built to WAI-ARIA specification with exhaustive keyboard navigation, focus management, and screen reader support.
- **Unstyled by default.** Zero design opinions means zero fighting with the library's aesthetic. Bring your own styling system.
- **Composable APIs.** Primitives use a compound component pattern with slot-based composition that gives you control over every rendered element.
- **Production-proven.** Radix primitives power thousands of production applications through both direct usage and shadcn/ui.
**When to use it:** You need accessible, behavior-only primitives and want complete control over styling. Great for teams building custom design systems.
**Trade-offs:** You need to bring all your own styling. The learning curve for the composition patterns can be steep for simpler use cases.
---
## 7. Ant Design
[Ant Design](https://ant.design/) is a comprehensive design system and component library created by Ant Group (Alibaba). It's especially popular in enterprise applications and the Chinese development community.
**Key strengths:**
- **Enterprise-grade components.** Complex components like Table (with sorting, filtering, pagination), Form (with validation), and Tree are mature and feature-rich.
- **Design system included.** Ant Design is a complete design system with design tokens, patterns, and guidelines — not just a component library.
- **Internationalization.** First-class i18n support with 60+ locale packages.
- **Component quality.** Each component handles dozens of edge cases that you'd otherwise need to build yourself.
**When to use it:** You're building a complex enterprise application, especially one that needs sophisticated data tables, forms, and tree views.
**Trade-offs:** The design aesthetic is distinctly "Ant Design" and theming it to look different requires substantial effort. Bundle size is significant. Accessibility support, while improving, still lags behind Radix/React Aria-based libraries.
---
## 8. Headless UI
[Headless UI](https://headlessui.com/) is a set of unstyled, accessible UI components from the Tailwind Labs team. It focuses on common interactive patterns — dropdowns, dialogs, tabs, comboboxes.
**Key strengths:**
- **Tailwind CSS integration.** Built by the Tailwind team, it works perfectly with Tailwind's utility classes and transition utilities.
- **Small, focused scope.** Only includes components that are genuinely hard to build accessibly (menus, listboxes, dialogs, etc.).
- **Lightweight.** Minimal bundle impact because of the focused component set.
- **Clean API.** Uses render props and compound components with a simple, predictable API.
**When to use it:** You're using Tailwind CSS and need a few accessible interactive components without a full UI library.
**Trade-offs:** Very small component set — you'll need other solutions for data tables, form inputs, date pickers, and most other patterns.
---
## 9. React Aria (Primitives)
[React Aria](https://react-spectrum.adobe.com/react-aria/) is Adobe's library of accessibility primitives for React. It provides hooks and components for building accessible UI from scratch.
**Key strengths:**
- **Industry-leading accessibility.** React Aria is arguably the most thoroughly accessible UI primitive library available. It handles internationalization, right-to-left layouts, touch interactions, and edge cases that most libraries miss.
- **Hooks + components.** Offers both low-level hooks (for maximum flexibility) and higher-level components (for convenience).
- **Platform-aware.** Adapts behavior based on device type, pointer type, and platform conventions.
- **Foundation for other libraries.** HeroUI, Adobe Spectrum, and other libraries build on React Aria, proving its reliability at scale.
**When to use it:** You're building a design system from scratch and need the strongest possible accessibility foundation. Also useful when you need specific primitives (like a color picker or calendar) that other libraries don't offer.
**Trade-offs:** Steeper learning curve than styled libraries. You need to bring all your own styling and composition patterns.
---
## 10. Ark UI
[Ark UI](https://ark-ui.com/) is a headless component library from the creators of Chakra UI, built on top of state machines for predictable behavior.
**Key strengths:**
- **State machine architecture.** Uses Zag.js state machines under the hood, making component behavior predictable and debuggable.
- **Framework-agnostic core.** The same state machines power React, Vue, and Solid versions of every component.
- **Modern patterns.** Includes components like Signature Pad, Pin Input, and Splitter that aren't commonly found in other headless libraries.
- **Styling flexibility.** Works with any styling solution — Tailwind, Panda CSS, vanilla CSS, CSS modules.
**When to use it:** You want headless components with predictable state management, or you need to share component logic across React, Vue, and Solid projects.
**Trade-offs:** Smaller community than Radix or React Aria. The state machine abstraction adds conceptual overhead for simple components.
---
## 11. Tremor
[Tremor](https://tremor.so/) is focused on dashboards and data visualization. Its current docs describe Tremor Raw as designed for React 18.2+ and Tailwind CSS 4.0+.
**Key strengths:**
- **Dashboard-first design.** Purpose-built resources for analytics, dashboard UI, and data display.
- **Tailwind native.** Integrates seamlessly with existing Tailwind projects without additional styling configuration.
- **Clean defaults.** Charts and metrics look polished out of the box with a cohesive design language.
- **Lightweight scope.** Focused on data display, so you pick what you need without pulling in an entire UI framework.
**When to use it:** You're building analytics dashboards or data-heavy interfaces and already use Tailwind CSS.
**Trade-offs:** Limited to dashboard-specific components. You'll need another library for general UI patterns like forms, navigation, and dialogs.
---
## 12. Park UI
[Park UI](https://park-ui.com/) is a styled component library built on Ark UI primitives, available in both Panda CSS and Tailwind CSS variants.
**Key strengths:**
- **Pre-styled Ark UI.** Takes Ark UI's headless components and adds polished, customizable styling — similar to what shadcn/ui does for Radix.
- **Dual styling support.** Available in both Panda CSS and Tailwind CSS variants, so you can pick the approach that fits your project.
- **Copy-paste model.** Like shadcn/ui, components are added to your project as source files you own and customize.
- **Design tokens.** Ships with a token system that makes global style changes straightforward.
**When to use it:** You like the shadcn/ui copy-paste model but prefer Ark UI's state-machine-based primitives over Radix, or you're using Panda CSS.
**Trade-offs:** Smaller community and ecosystem compared to shadcn/ui. Fewer third-party extensions and themes.
---
## How to Choose
There's no single "best" library — the right choice depends on your project's constraints:
- **Starting a new project with Tailwind v4?** HeroUI gives you the most modern stack with React Aria accessibility, compound components, and AI tooling.
- **Want full ownership of component code?** shadcn/ui or Park UI let you copy components into your project.
- **Building enterprise apps with complex data needs?** MUI's data grid or Ant Design's table component are hard to beat.
- **Need maximum accessibility compliance?** HeroUI's React Aria foundation provides the strongest accessibility out of the box.
- **Want a broad UI toolkit with quality?** HeroUI covers all core UI patterns with deep accessibility; pair with dedicated libraries for specialized needs like rich text editors.
- **Working across multiple frameworks?** Ark UI's state machines work in React, Vue, and Solid.
## Get Started with HeroUI
If you're starting a new React project and want accessible, beautifully designed components with Tailwind CSS v4, give HeroUI a try:
- [Quick Start Guide](/docs/react/getting-started/quick-start)
- [Component Documentation](/docs/react/components)
- [GitHub Repository](https://github.com/heroui-inc/heroui)
- [Discord Community](https://discord.gg/heroui)
apps/docs/content/blog/en/build-react-dashboard-with-heroui.mdx
+414
View File
@@ -0,0 +1,414 @@
---
title: "How to Build a React Dashboard with HeroUI Pro"
description: "Create responsive admin dashboards with HeroUI and HeroUI Pro using AppLayout, Sidebar, Navbar, KPI, DataGrid, and chart components."
date: "2026-05-11"
author: "Junior Garcia"
authorHandle: "@jrgarciadev"
authorUrl: "https://x.com/jrgarciadev"
authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4"
tags: ["react", "dashboard", "tutorial", "heroui", "admin"]
image: "/images/blog/build-react-dashboard-with-heroui.jpg"
draft: true
---
I've watched too many teams spend their first two sprints hand-rolling a sidebar, a responsive navbar, and a metrics card layout — only to rip it out later when the requirements get real. If you have HeroUI Pro, skip that phase entirely.
This post shows the Pro-first approach: start with `AppLayout`, `Sidebar`, `Navbar`, `KPI`, `DataGrid`, and chart components, then plug in your data. The dashboard template already handles the layout, responsive behavior, and mobile navigation.
## Project Setup
Install HeroUI and HeroUI Pro packages:
```bash
npm install @heroui/styles @heroui/react @heroui-pro/react
```
HeroUI Pro requires access to the Pro package registry. The dashboard template uses these style imports:
```css
@import "@heroui/styles/css";
@import "@heroui-pro/react/css";
@source "../**/*.{ts,tsx}";
body {
background-color: var(--background);
}
```
## Use AppLayout for the Frame
The app frame should come from HeroUI Pro `AppLayout`, not a custom flex layout.
```tsx
"use client";
import type {ReactNode} from "react";
import {AppLayout} from "@heroui-pro/react";
import {usePathname, useRouter} from "next/navigation";
import {useCallback} from "react";
import {DashboardNavbar} from "./dashboard-navbar";
import {DashboardSidebar} from "./dashboard-sidebar";
export function AppShell({children}: {children: ReactNode}) {
const router = useRouter();
const pathname = usePathname();
const navigate = useCallback((href: string) => router.push(href), [router]);
return (
<AppLayout
navbar={<DashboardNavbar title="Dashboard" />}
navigate={navigate}
sidebar={<DashboardSidebar pathname={pathname} />}
sidebarCollapsible="offcanvas"
>
{children}
</AppLayout>
);
}
```
`AppLayout` handles the relationship between the sidebar, navbar, mobile menu, and content region. Keep it as the app shell and customize inside the slots.
## Use Pro Sidebar and Navbar
HeroUI Pro ships a `Sidebar` compound component and a `Navbar` compound component. The dashboard template uses both.
```tsx
"use client";
import {Bell, Magnifier} from "@gravity-ui/icons";
import {Button} from "@heroui/react";
import {AppLayout, Navbar, Sidebar} from "@heroui-pro/react";
export function DashboardNavbar({title}: {title: string}) {
return (
<Navbar maxWidth="full">
<Navbar.Header>
<AppLayout.MenuToggle />
<Sidebar.Trigger />
<h1 className="text-foreground truncate text-xl font-semibold">{title}</h1>
<Navbar.Spacer />
<Button isIconOnly aria-label="Search" size="sm" variant="tertiary">
<Magnifier className="size-4" />
</Button>
<Button isIconOnly aria-label="Notifications" size="sm" variant="tertiary">
<Bell className="size-4" />
</Button>
</Navbar.Header>
</Navbar>
);
}
```
For navigation, render `Sidebar.MenuItem` items instead of building custom active-link styles:
```tsx
"use client";
import {ChartColumn, Gear, House, Receipt} from "@gravity-ui/icons";
import {Sidebar} from "@heroui-pro/react";
const items = [
{href: "/", icon: House, label: "Dashboard"},
{href: "/orders", icon: Receipt, label: "Orders"},
{href: "/analytics", icon: ChartColumn, label: "Analytics"},
{href: "/settings", icon: Gear, label: "Settings"},
];
export function DashboardSidebar({pathname}: {pathname: string}) {
return (
<>
<Sidebar>
<Sidebar.Content>
<Sidebar.Group>
<Sidebar.Menu aria-label="Dashboard navigation">
{items.map((item) => {
const Icon = item.icon;
const isCurrent =
item.href === "/" ? pathname === "/" : pathname.startsWith(item.href);
return (
<Sidebar.MenuItem
key={item.href}
href={item.href}
id={item.href}
isCurrent={isCurrent}
textValue={item.label}
>
<Sidebar.MenuIcon>
<Icon className="size-4" />
</Sidebar.MenuIcon>
<Sidebar.MenuLabel>{item.label}</Sidebar.MenuLabel>
</Sidebar.MenuItem>
);
})}
</Sidebar.Menu>
</Sidebar.Group>
</Sidebar.Content>
</Sidebar>
<Sidebar.Mobile>{/* Reuse the same menu content for mobile. */}</Sidebar.Mobile>
</>
);
}
```
The full Pro template also includes a header profile area, footer items, badges, and mobile content reuse.
## Use KPI for Metrics
Do not rebuild metric cards with `Card` unless you need a one-off design. Use `KPI` from HeroUI Pro.
```tsx
"use client";
import {KPI} from "@heroui-pro/react";
const chartData = [
{x: 1, y: 12},
{x: 2, y: 18},
{x: 3, y: 16},
{x: 4, y: 24},
];
export function KpiRow() {
return (
<div className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-4">
<KPI>
<KPI.Header>
<KPI.Title>Revenue</KPI.Title>
</KPI.Header>
<KPI.Content>
<KPI.Value currency="USD" maximumFractionDigits={0} style="currency" value={45231} />
<KPI.Trend trend="up">12.5%</KPI.Trend>
</KPI.Content>
<KPI.Chart color="var(--color-accent)" data={chartData} height={60} strokeWidth={1.5} />
</KPI>
</div>
);
}
```
The dashboard template uses this same pattern for analytics KPIs and finance KPIs.
## Use Pro Charts
HeroUI Pro chart components keep chart styling aligned with the rest of the design system.
```tsx
"use client";
import {Card} from "@heroui/react";
import {LineChart, NumberValue, TrendChip} from "@heroui-pro/react";
const data = [
{day: "Mon", sessions: 1800, users: 1200},
{day: "Tue", sessions: 2400, users: 1700},
{day: "Wed", sessions: 2200, users: 1600},
{day: "Thu", sessions: 3100, users: 2100},
];
export function SessionsCard() {
const total = data.reduce((sum, point) => sum + point.sessions, 0);
return (
<Card className="rounded-2xl">
<Card.Header className="flex-row items-start justify-between gap-4">
<div className="flex flex-col gap-1">
<Card.Title className="text-base">Sessions over time</Card.Title>
<div className="flex items-baseline gap-2">
<NumberValue
className="text-foreground text-2xl font-semibold tabular-nums"
maximumFractionDigits={0}
value={total}
/>
<TrendChip trend="up">18.3%</TrendChip>
</div>
<span className="text-muted text-xs">vs. previous 30 days</span>
</div>
</Card.Header>
<Card.Content>
<LineChart data={data} height={240}>
<LineChart.Grid vertical={false} />
<LineChart.XAxis dataKey="day" minTickGap={32} tickMargin={8} />
<LineChart.YAxis width={40} />
<LineChart.Line
dataKey="sessions"
dot={false}
name="Sessions"
stroke="var(--chart-2)"
strokeWidth={2}
type="monotone"
/>
<LineChart.Line
dataKey="users"
dot={false}
name="Users"
stroke="var(--chart-4)"
strokeWidth={2}
type="monotone"
/>
<LineChart.Tooltip content={<LineChart.TooltipContent />} />
</LineChart>
</Card.Content>
</Card>
);
}
```
Use the chart components from Pro for dashboard analytics, then swap the sample arrays for your real metrics.
## Use DataGrid for Tables
Dashboards usually need dense, sortable tables. Use Pro `DataGrid` instead of composing raw table markup.
```tsx
"use client";
import type {DataGridColumn, DataGridSortDescriptor} from "@heroui-pro/react";
import {Avatar, SearchField} from "@heroui/react";
import {DataGrid} from "@heroui-pro/react";
import {useMemo, useState} from "react";
type Member = {
id: string;
name: string;
email: string;
avatar: string;
role: string;
};
const members: Member[] = [
{
id: "1",
name: "Kate Moore",
email: "kate@example.com",
avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue-light.jpg",
role: "Admin",
},
];
export function MembersTable() {
const [search, setSearch] = useState("");
const [sortDescriptor, setSortDescriptor] = useState<DataGridSortDescriptor>({
column: "name",
direction: "ascending",
});
const filteredMembers = useMemo(() => {
if (!search) return members;
const q = search.toLowerCase();
return members.filter(
(member) => member.name.toLowerCase().includes(q) || member.email.toLowerCase().includes(q),
);
}, [search]);
const columns = useMemo<DataGridColumn<Member>[]>(
() => [
{
accessorKey: "name",
allowsSorting: true,
cell: (item) => (
<div className="flex items-center gap-3">
<Avatar className="size-8">
<Avatar.Image alt={item.name} src={item.avatar} />
<Avatar.Fallback>{item.name[0]}</Avatar.Fallback>
</Avatar>
<div className="flex min-w-0 flex-col">
<span className="text-xs font-medium">{item.name}</span>
<span className="text-muted text-xs">{item.email}</span>
</div>
</div>
),
header: "Member",
id: "name",
isRowHeader: true,
minWidth: 220,
},
{
accessorKey: "role",
allowsSorting: true,
header: "Role",
id: "role",
minWidth: 160,
},
],
[],
);
return (
<div className="flex flex-col gap-4">
<SearchField className="w-full sm:w-[220px]" name="member-search" onChange={setSearch}>
<SearchField.Group>
<SearchField.SearchIcon />
<SearchField.Input placeholder="Search..." />
<SearchField.ClearButton />
</SearchField.Group>
</SearchField>
<DataGrid
aria-label="Members"
columns={columns}
contentClassName="min-w-[520px]"
data={filteredMembers}
getRowId={(item) => item.id}
sortDescriptor={sortDescriptor}
onSortChange={setSortDescriptor}
/>
</div>
);
}
```
This matches the template's table direction: typed columns, a controlled sort descriptor, search outside the grid, and `getRowId` for stable row identity.
## Compose the Dashboard Page
The page should mostly assemble widgets. In the Pro template, the dashboard view looks like this:
```tsx
"use client";
import {DashboardToolbar} from "../widgets/dashboard-toolbar";
import {EmployeesTable} from "../widgets/employees-table";
import {KpiRow} from "../widgets/kpi-row";
import {SalesPerformanceCard} from "../widgets/sales-performance-card";
import {TrafficSourceCard} from "../widgets/traffic-source-card";
export function DashboardPage() {
return (
<div className="mx-auto flex max-w-7xl flex-col gap-4 px-5 pb-10 pt-4">
<DashboardToolbar />
<KpiRow />
<div className="grid grid-cols-1 gap-3 lg:grid-cols-2">
<SalesPerformanceCard />
<TrafficSourceCard />
</div>
<EmployeesTable />
</div>
);
}
```
That is the main architectural point: the page should read like product composition, not infrastructure.
## Why HeroUI for Dashboards
Dashboards are dense — data tables, form controls, navigation, and overlays on a single screen. HeroUI handles the accessibility and styling for all of those pieces so you can focus on your data layer.
- **Data tables that handle accessibility for you.** Sortable columns, row selection, keyboard navigation, and screen reader announcements come from React Aria. You don't reimplement them per table.
- **Static CSS for data-heavy pages.** Tailwind v4 generates all styles at build time. Dashboards with KPI cards, charts, and grids don't pay a runtime styling tax.
- **Pro primitives instead of hand-rolled infrastructure.** AppLayout, Sidebar, Navbar, KPI, DataGrid, and chart components from [HeroUI Pro](https://heroui.com/pro) save weeks of dashboard scaffold work.
- **AI assistants that know the Pro API.** The [MCP server](/docs/react/getting-started/mcp-server) and [agent skills](/docs/react/getting-started/agent-skills) let AI tools scaffold dashboard views with correct component APIs instead of guessing.
## Next Steps
- Start from the [HeroUI Pro](https://heroui.com/pro) dashboard template if you have Pro access.
- Replace the mock files in `src/data/*` with your API, database, or analytics source.
- Keep `AppLayout`, `Sidebar`, `Navbar`, `KPI`, `DataGrid`, and Pro charts as the foundation.
- Use base [HeroUI components](/docs/react/components) for local UI that does not need a Pro primitive.
apps/docs/content/blog/en/choosing-react-native-ui-library.mdx
+96
View File
@@ -0,0 +1,96 @@
---
title: "Choosing a React Native UI Library"
description: "A practical framework for choosing a React Native UI library, and where HeroUI Native fits."
date: "2026-05-12"
author: "Junior Garcia"
authorHandle: "@jrgarciadev"
authorUrl: "https://x.com/jrgarciadev"
authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4"
tags: ["native", "react-native", "ui-libraries", "comparison"]
image: "/images/blog/choosing-react-native-ui-library.jpg"
draft: true
---
Choosing a React Native UI library is not just a component-count decision. It is a maintenance decision, a design decision, and increasingly an AI workflow decision.
The library you choose becomes the vocabulary your team uses every day. It shapes how designers hand off screens, how engineers compose interfaces, how quickly you can fix accessibility issues, and how well AI agents generate code that actually compiles.
This guide explains how we think about that decision, and why HeroUI Native is built the way it is.
## What to Evaluate
Before comparing libraries, write down what your product needs:
- Are you building a consumer app, internal tool, SaaS companion app, marketplace, fintech app, or mobile-first product?
- Do you need bottom sheets, dialogs, menus, tabs, forms, toasts, skeletons, and list patterns?
- Is your design system already defined in Figma?
- Do you need AI assistants to generate UI reliably?
- Does your team want a package that updates over time, or copied source code you fully own?
Those questions matter more than a screenshot gallery.
## Package vs. Copy-Paste
Copy-paste UI can be useful when you need total code ownership. The trade-off is maintenance. Once the code is in your app, your team owns the updates, accessibility fixes, dependency changes, and design consistency.
HeroUI Native takes the package approach:
- Install `heroui-native`.
- Configure Uniwind and the provider once.
- Compose components through documented APIs.
- Update the package when fixes and improvements ship.
- Use MCP/LLM docs so AI tools can read current component documentation.
That does not mean a package is always better. If your team has a dedicated design system group and wants to own every line of component code, copied source may fit. But if your team wants to ship product screens without becoming a component-maintenance team, a maintained package is usually the healthier default.
## Design Quality Is a Feature
Mobile apps are judged in milliseconds. A button press, sheet transition, input focus state, disabled control, or empty state can make an app feel cared for or unfinished.
HeroUI Native is intentionally opinionated about the baseline:
- Semantic component variants create a clear visual hierarchy.
- Components are designed to look complete before customization.
- Theming happens through CSS variables and Uniwind.
- Animated components use React Native animation libraries instead of web-only assumptions.
- Component APIs follow compound composition so you can adjust structure without forking internals.
The goal is not to lock you into one visual identity. The goal is to start from a designed system rather than a pile of primitives.
## Ecosystem Fit
HeroUI Native is strongest when you want one ecosystem across product surfaces:
- Web product: [HeroUI React](/docs/react/getting-started/quick-start)
- Mobile product: [HeroUI Native](/docs/native/getting-started)
- Premium app surfaces: [HeroUI Pro](https://heroui.com/pro)
- Design handoff: [HeroUI Figma Kit V3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
- AI workflow: [Native MCP Server](/docs/native/getting-started/mcp-server), [llms.txt](/docs/native/getting-started/llms-txt), and [Agent Skills](/docs/native/getting-started/agent-skills)
That ecosystem is the advantage. A component library by itself saves some time. A design system, docs, Figma kit, AI context, and maintained package save coordination cost.
## Where HeroUI Native Is Different
HeroUI Native is built specifically for React Native. It does not ask you to use web imports or CSS files that do not belong in mobile apps.
Use Native patterns:
```tsx
import {Button} from "heroui-native";
<Button variant="primary" onPress={() => console.log("Pressed")}>
<Button.Label>Continue</Button.Label>
</Button>;
```
Avoid web patterns:
Do not use the HeroUI web package or web-only event handlers in React Native screens.
HeroUI Native uses `onPress`, `HeroUINativeProvider`, `GestureHandlerRootView`, Uniwind, and native overlay/portal patterns because those are the right abstractions for mobile.
## Recommendation
Choose HeroUI Native when your team values design quality, maintainability, and ecosystem leverage. It is especially compelling if you already use HeroUI on the web, work from Figma, or build with AI coding assistants.
Start with the [Quick Start](/docs/native/getting-started/quick-start), then read the [Design Principles](/docs/native/getting-started/design-principles) before building your first screen.
apps/docs/content/blog/en/design-to-code-with-heroui-native.mdx
+125
View File
@@ -0,0 +1,125 @@
---
title: "Design to Code with HeroUI Native"
description: "How HeroUI Native connects Figma, code, and AI-assisted mobile development."
date: "2026-05-13"
author: "Junior Garcia"
authorHandle: "@jrgarciadev"
authorUrl: "https://x.com/jrgarciadev"
authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4"
tags: ["native", "react-native", "design-system", "figma", "ai"]
image: "/images/blog/design-to-code-with-heroui-native.jpg"
draft: true
---
The hardest part of a mobile design system is not drawing components. It is keeping design, code, documentation, and generated AI output aligned over time.
HeroUI Native is built for that workflow. The library gives developers a maintained React Native component system, gives designers a shared HeroUI visual language through Figma, and gives AI assistants structured documentation through MCP, llms.txt, and skills.
## The Problem
Most teams drift in predictable ways:
- Figma components use one naming system.
- React Native components use another.
- Design tokens get translated by hand.
- AI agents guess props from old examples.
- Engineers copy a component once, customize it, and rarely bring upstream fixes back in.
The result is subtle inconsistency. One screen has different spacing. Another uses the wrong disabled state. A generated component imports web HeroUI into a native app. The first version ships, but the system becomes harder to maintain.
HeroUI Native is designed to reduce that drift.
## Shared Mental Model
HeroUI Native uses the same product-level ideas as the rest of the HeroUI ecosystem:
- Semantic variants like `primary`, `secondary`, and `tertiary`.
- Compound components for flexible composition.
- Theme variables for semantic colors and surfaces.
- Component documentation with anatomy, props, examples, and usage patterns.
- AI-readable docs for agents.
The implementation is native, not web. HeroUI Native uses React Native, Uniwind, `HeroUINativeProvider`, and mobile interaction patterns. But the design language stays familiar.
```tsx
import {Button, Card} from "heroui-native";
<Card>
<Card.Header>
<Card.Title>Workspace</Card.Title>
<Card.Description>Invite your team and manage access.</Card.Description>
</Card.Header>
<Card.Body>{/* Screen content */}</Card.Body>
<Card.Footer>
<Button variant="primary">
<Button.Label>Invite member</Button.Label>
</Button>
</Card.Footer>
</Card>;
```
## Figma Kit V3
The [HeroUI Figma Kit V3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3) is the design-side entry point for the ecosystem. It is linked from the Native docs so teams can work from the same visual system while building mobile screens.
Use it to:
- Start from HeroUI's visual language instead of blank frames.
- Keep component names and variants close to the code model.
- Align designers and developers on hierarchy, states, and spacing.
- Create mobile product screens that feel connected to the rest of the HeroUI ecosystem.
Figma does not replace implementation details like keyboard handling, safe areas, bottom sheets, or screen reader behavior. But a shared kit reduces the translation cost between design and code.
## AI Context That Knows Native
AI coding tools are useful only when they have current context. Without that, they often mix web and native APIs.
HeroUI Native provides dedicated AI entry points:
- [/native/llms.txt](/native/llms.txt) for a quick Native documentation index.
- [/native/llms-full.txt](/native/llms-full.txt) for complete Native documentation.
- [/native/llms-components.txt](/native/llms-components.txt) for component docs only.
- [/native/llms-patterns.txt](/native/llms-patterns.txt) for common patterns.
- [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server), published as `@heroui/native-mcp`.
- [HeroUI Native Agent Skills](/docs/native/getting-started/agent-skills).
That matters because Native code has different rules:
- Import from `heroui-native`.
- Use React Native press handlers such as `onPress`.
- Configure `HeroUINativeProvider`.
- Wrap the app with `GestureHandlerRootView`.
- Use Uniwind and `heroui-native/styles`.
- Use Native component anatomy, not web component anatomy.
The MCP server and skills help agents follow those rules.
## A Practical Workflow
Here is the workflow we recommend:
1. **Design from the Figma kit.** Start from HeroUI's component language instead of one-off mobile components.
2. **Install HeroUI Native correctly.** Follow the [Quick Start](/docs/native/getting-started/quick-start) so Uniwind, peer dependencies, styles, and providers are configured.
3. **Give agents the docs.** Add the [MCP server](/docs/native/getting-started/mcp-server) or reference [/native/llms-full.txt](/native/llms-full.txt).
4. **Build screens with compound components.** Compose components using dot notation and semantic variants.
5. **Customize through theme variables.** Keep brand-level changes in the theming layer, not scattered across every screen.
6. **Update through the package.** Treat HeroUI Native as a maintained dependency, not a copied snapshot.
## Why This Helps
Design-to-code is not about removing engineers or designers. It is about reducing translation loss.
HeroUI Native helps because:
- Designers start from the HeroUI visual system.
- Developers get a maintained React Native package.
- AI assistants get current component docs.
- Teams keep a consistent vocabulary across web and mobile.
- The library can evolve without every app owning every internal component detail.
That is the long-term value: not just faster first screens, but fewer inconsistencies as the app grows.
## Next Step
Install the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server) in your editor, then ask your assistant to build a screen using the [Quick Start](/docs/native/getting-started/quick-start) and the components in [All Components](/docs/native/components).
apps/docs/content/blog/en/heroui-vs-chakra-ui.mdx
+235
View File
@@ -0,0 +1,235 @@
---
title: "HeroUI vs Chakra UI: Which React UI Library Should You Choose in 2026?"
description: "A comprehensive comparison of HeroUI and Chakra UI — accessibility, styling approaches, performance, and when to choose each React component library."
date: "2026-05-14"
author: "Junior Garcia"
authorHandle: "@jrgarciadev"
authorUrl: "https://x.com/jrgarciadev"
authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4"
tags: ["comparison", "heroui", "chakra-ui", "react"]
draft: true
---
If you're picking a React component library in 2026, HeroUI and Chakra UI are both strong contenders. HeroUI styles components with Tailwind CSS v4 utility classes and builds accessibility on React Aria, using a compound component API (`Card.Header`, `Modal.Body`) instead of style props. Chakra UI pioneered the style-props pattern and has rebuilt on Panda CSS and Ark UI. Both ship accessible components — but they take fundamentally different approaches to styling, component design, and developer tooling that matter more than you might think.
This guide walks through where each library shines, where it falls short, and how to decide which one fits your project.
## The TL;DR
| Feature | HeroUI v3 | Chakra UI v3 |
|---------|-----------|--------------|
| **Styling** | Tailwind CSS v4 (static CSS) | Panda CSS API-based styling system and style props |
| **Accessibility** | React Aria (Adobe) | Ark UI / Zag.js (Chakra team) |
| **Component API** | Compound components + className | Style props on components |
| **CSS output** | Static CSS from Tailwind and HeroUI styles | Runtime styling in the stable Chakra setup |
| **AI tooling** | MCP server, llms.txt, agent skills | MCP server and public docs |
| **Theming** | CSS custom properties + `@theme` | Theme tokens + semantic tokens |
| **React 19** | Supported | Supported |
| **Server components** | Static pieces can stay server-rendered; interactive pieces use client boundaries | Depends on component and styling usage |
## Styling: Two Different Philosophies
This is the biggest architectural difference between the two libraries, and it's worth understanding deeply because it affects everything downstream — from how you customize components to how your app performs in production.
### Chakra UI: Style Props
Chakra pioneered the "style props" pattern in React. Instead of writing CSS classes, you style components through JSX props:
```tsx
import { Box, Button } from "@chakra-ui/react";
<Box bg="blue.500" p={4} borderRadius="lg">
<Button colorPalette="blue" size="lg">
Click me
</Button>
</Box>
```
This is ergonomic for quick prototyping. You stay in JSX, your styles are co-located with your markup, and the design token system (`blue.500`, `p={4}`) keeps things consistent. Chakra's current theming docs describe the styling system as built around Panda CSS APIs like `defineConfig`, `createSystem`, recipes, slot recipes, tokens, and semantic tokens.
The trade-off is that style props can make JSX verbose for complex layouts. A card with a dozen styling tweaks ends up with more prop noise than markup, and the default styling model is still different from a static CSS/Tailwind setup.
### HeroUI: Tailwind CSS v4
HeroUI takes the opposite approach — components are styled with Tailwind CSS utility classes, and you customize them the same way you'd customize any Tailwind element:
```tsx
import { Card, Button } from "@heroui/react";
<Card className="bg-blue-500 p-4 rounded-lg">
<Card.Header>
<Card.Title>My Card</Card.Title>
</Card.Header>
<Card.Content>
<Button size="lg">Click me</Button>
</Card.Content>
</Card>
```
Because Tailwind v4 and HeroUI styles are CSS-first, there is no component-level CSS-in-JS runtime in the HeroUI styling path. HeroUI's theming system uses CSS custom properties and Tailwind's `@theme` directive, so you can swap visual systems by changing variables.
If you're already using Tailwind in your project, HeroUI slots in naturally. If you're not, adopting Tailwind is a separate decision that comes with its own learning curve.
### Which styling approach is better?
Neither is objectively superior — it depends on your team.
Style props are great when you want to move fast and keep everything in JSX. They're intuitive for developers who think in "component properties" rather than "CSS classes." But they create a tight coupling between your component library and your styling strategy.
Tailwind utilities are great when you want a universal styling language that works the same way on library components and custom components. The build-time approach means better performance, and the utility-first workflow is something most React developers already know in 2026.
## Accessibility Foundations
Both libraries take accessibility seriously, but they build on different foundations.
### HeroUI: React Aria
HeroUI is built on [React Aria](https://react-spectrum.adobe.com/react-aria/), Adobe's accessibility primitives. React Aria handles keyboard navigation, screen reader announcements, focus management, and ARIA attributes for every component. It's the same foundation that powers Adobe's own design system (Spectrum), and it's one of the most thoroughly tested accessibility layers in the React ecosystem.
What this means in practice: HeroUI components handle edge cases that many libraries miss. Focus trapping in modals works correctly with screen readers. Comboboxes announce option counts. Date pickers support keyboard navigation across months and years. These aren't features you'd notice in a demo, but they're critical for shipping accessible software.
### Chakra UI: Ark UI / Zag.js
Chakra v3 rebuilt its accessibility layer on [Ark UI](https://ark-ui.com/) and [Zag.js](https://zagjs.com/), both maintained by the Chakra team. Zag uses state machines to model component behavior, which makes the logic predictable and testable. Ark UI wraps Zag into framework-specific components.
This is a solid approach, and Chakra's accessibility is genuinely good. The main difference is maturity — React Aria has been in production at Adobe for years and has a larger surface area of accessibility testing. Zag.js is newer and still expanding its component coverage.
### The practical difference
For most applications, both libraries will produce accessible UIs. The gap shows up in complex components — date pickers, comboboxes, drag-and-drop — where React Aria's deeper investment in accessibility edge cases gives HeroUI an advantage.
## Component API Design
This is where the day-to-day developer experience diverges most noticeably.
### HeroUI: Compound Components
HeroUI uses a compound component pattern where a parent component exposes sub-components through dot notation:
```tsx
import { Modal, Button } from "@heroui/react";
<Modal>
<Button>Open Modal</Button>
<Modal.Backdrop>
<Modal.Container>
<Modal.Dialog>
<Modal.CloseTrigger />
<Modal.Header>
<Modal.Heading>Confirm Action</Modal.Heading>
</Modal.Header>
<Modal.Body>Are you sure?</Modal.Body>
<Modal.Footer>
<Button variant="ghost">Cancel</Button>
<Button>Confirm</Button>
</Modal.Footer>
</Modal.Dialog>
</Modal.Container>
</Modal.Backdrop>
</Modal>
```
This is more verbose than a flat prop API, but it gives you complete control over the component's structure. You can reorder parts, add custom elements between them, or omit parts entirely. It's the same pattern used by Radix UI, and it scales well for complex UIs.
### Chakra UI: Flat Components with Style Props
Chakra components are flatter and rely on props for configuration:
```tsx
import { DialogRoot, DialogContent, DialogHeader, DialogBody, DialogFooter } from "@chakra-ui/react";
<DialogRoot>
<DialogContent>
<DialogHeader>Confirm Action</DialogHeader>
<DialogBody>Are you sure?</DialogBody>
<DialogFooter>
<Button variant="ghost">Cancel</Button>
<Button>Confirm</Button>
</DialogFooter>
</DialogContent>
</DialogRoot>
```
Chakra v3 moved toward a more composable approach compared to v2, but the styling still happens through props rather than class names. This makes the JSX self-documenting in one sense (you can see all the styles) but noisy in another (the styles obscure the structure).
## Performance
Performance differences between modern component libraries are often overstated, but there are real architectural factors worth considering.
### Build-time vs. runtime CSS
HeroUI generates all CSS at build time through Tailwind v4. Your production bundle includes only the utility classes your components actually use, and there's zero JavaScript overhead for style computation at runtime.
Chakra's styling API is much more structured than the older Chakra v2 era and is built around the Panda CSS API. It is still a different authoring model from HeroUI's Tailwind/CSS-variable path, so teams should test the exact runtime and bundle impact in their own app.
### Bundle size
HeroUI components are thin wrappers around React Aria primitives plus CSS classes. Chakra components carry a richer style-props and theme system. The practical impact depends on which components you use and how aggressively your app splits routes.
### Server components
HeroUI's static pieces can stay in React Server Component trees, while interactive pieces need client boundaries. Chakra's behavior depends on which components and style props you use, so I would test the exact pages you care about before making performance promises.
## AI Tooling
This is an area where HeroUI has a clear, measurable advantage.
### HeroUI's AI stack
HeroUI ships three tools specifically designed for AI coding assistants:
- **MCP server.** A [Model Context Protocol server](/docs/react/getting-started/mcp-server) that exposes component documentation, API references, and code examples to AI agents. When your AI assistant has access to this, it can look up the exact props, compound component structure, and usage patterns for any HeroUI component — instead of guessing.
- **llms.txt.** A structured text file at [heroui.com/llms.txt](/docs/react/getting-started/llms-txt) that gives LLMs a condensed reference of the entire library. This is the equivalent of giving your AI assistant a cheat sheet.
- **Agent skills.** Pre-built [skill files](/docs/react/getting-started/agent-skills) for AI coding tools like Cursor and Claude Code that teach agents how to scaffold components, use the correct import paths, and follow HeroUI conventions.
In practice, this gives AI assistants a better chance of generating current HeroUI v3 code. They can look up the compound component patterns, prop names, and import paths instead of guessing from mixed training data.
### Chakra UI's AI support
Chakra's docs now point developers to an MCP server, so it is not accurate to say Chakra has no AI support. The practical difference is that HeroUI's AI context is specific to HeroUI's v3 compound components, Tailwind v4 styling, and package API, while Chakra's context teaches Chakra's style-prop and system APIs.
### Why this matters
If you're using AI coding assistants daily (and in 2026, most developers are), the quality of AI-generated code directly affects your productivity. Getting correct code on the first generation saves you from debugging hallucinated props, wrong imports, and deprecated patterns.
## Ecosystem and Community
Both libraries have active communities, good TypeScript support, and work with Next.js. HeroUI's community is growing quickly with strong documentation, an active Discord, and HeroUI Pro for teams that need premium components.
HeroUI also invests heavily in AI developer tooling — MCP servers, llms.txt, and agent skills — which is increasingly important as AI-assisted development becomes the default workflow.
## Design Quality
Design quality is subjective, but there are measurable differences in how these libraries handle visual polish.
HeroUI ships with refined default animations, consistent spacing tokens, and a design system that looks polished out of the box. Components have subtle transitions, well-balanced proportions, and sensible defaults that work without customization. The theme system supports variants like "glass" and "brutalism" for distinct visual identities.
Chakra provides good-looking defaults as well, especially in v3. The design token system is well-organized and the components are clean. However, HeroUI's defaults tend to feel more opinionated and "designed" — there's more attention to micro-interactions, shadows, and spacing out of the box.
If you plan to heavily customize the visual design anyway, this matters less. If you want something that looks great with minimal theming effort, HeroUI has an edge.
## When to Choose Each
### Choose HeroUI if:
- You're already using Tailwind CSS (or want to)
- Accessibility is a hard requirement and you want React Aria's depth
- You use AI coding assistants and want first-class tooling support
- You prefer compound component APIs that give you structural control
- You want polished defaults with minimal custom theming
- You're building with React 19 and want good server component support
- Performance matters and you prefer a static CSS styling path
### When Chakra UI might work
Chakra UI can be a reasonable choice if your team doesn't use Tailwind CSS and prefers styling through component props, or if you're maintaining an existing Chakra codebase. However, Chakra's reliance on Panda CSS and runtime styling introduces trade-offs in performance and bundle size that HeroUI avoids entirely with static CSS.
## Summary
For new projects in 2026, HeroUI's modern stack — React Aria accessibility, Tailwind CSS v4 static styling, compound component architecture, and first-party AI tooling — provides a stronger foundation for building production applications. If you're starting fresh, HeroUI is the clear choice.
---
## Get Started with HeroUI
Ready to try HeroUI? Check out the [quick start guide](/docs/react/getting-started/quick-start) to set up your first project in under five minutes. If you want to see components in action, browse the [component docs](/docs/react/components) or install the [MCP server](/docs/react/getting-started/mcp-server) to let your AI assistant handle the boilerplate.
apps/docs/content/blog/en/heroui-vs-mantine.mdx
+266
View File
@@ -0,0 +1,266 @@
---
title: "HeroUI vs Mantine: Which React Component Library is Right for You in 2026?"
description: "Comparing HeroUI and Mantine — two popular React component libraries with different approaches to styling, component breadth, and developer tooling."
date: "2026-05-15"
author: "Junior Garcia"
authorHandle: "@jrgarciadev"
authorUrl: "https://x.com/jrgarciadev"
authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4"
tags: ["comparison", "heroui", "mantine", "react"]
draft: true
---
HeroUI and Mantine are both modern, well-maintained React component libraries with genuine strengths. But they're built on very different philosophies. Mantine is a batteries-included toolkit with a very broad component and hooks catalog; Mantine's homepage currently describes it as `120+` components and `70+` hooks. HeroUI pairs React Aria's deep accessibility layer with Tailwind CSS v4 and a compound component API, plus first-party AI tooling through MCP, llms.txt, and agent skills.
This comparison breaks down the real differences — not just feature checklists, but the trade-offs that actually affect your daily development workflow.
## Quick Comparison
| Feature | HeroUI v3 | Mantine v8 |
|---------|-----------|------------|
| **Components** | Broad focused set | 120+ components |
| **Styling** | Tailwind CSS v4 (CSS-first) | CSS files / CSS Modules + PostCSS |
| **Accessibility** | React Aria (Adobe) | Built into Mantine components |
| **Hooks library** | None (use React Aria hooks for interaction/accessibility needs) | 70+ hooks |
| **Component API** | Compound components | Flat components with props |
| **AI tooling** | MCP server, llms.txt, agent skills | MCP server, llms.txt, skills |
| **Form handling** | Works with any form library | Built-in @mantine/form |
| **CSS runtime** | Zero | Zero |
| **Theming** | CSS custom properties + @theme | CSS variables + MantineProvider |
| **React 19** | Supported | Supported |
## Component Coverage
Mantine ships a large number of components across several packages, including a carousel, rich text editor, spotlight search, and notification system:
- **@mantine/core** — Buttons, inputs, modals, navigation, layout, typography
- **@mantine/dates** — Date pickers, calendars, date range inputs
- **@mantine/charts** — Charts built on Recharts
- **@mantine/notifications** — Toast notifications system
- **@mantine/tiptap** — Rich text editor
- **@mantine/spotlight** — Command palette / spotlight search
- **@mantine/dropzone** — File upload with drag-and-drop
- **@mantine/carousel** — Carousel / slider component
- **@mantine/nprogress** — Page loading progress bar
Mantine ships a large number of components, though breadth comes with trade-offs — larger bundle sizes, more APIs to learn, and components that may not all receive the same level of polish and accessibility testing.
HeroUI takes a more focused approach. The core library covers the essential component set — buttons, forms, modals, tables, navigation, data display — with depth rather than breadth. Components like `Table` support sorting, selection, column resizing, and infinite scrolling out of the box:
```tsx
import { Table } from "@heroui/react";
<Table>
<Table.ScrollContainer>
<Table.Content aria-label="Users">
<Table.Header>
<Table.Column allowsSorting>Name</Table.Column>
<Table.Column allowsSorting>Role</Table.Column>
<Table.Column>Status</Table.Column>
</Table.Header>
<Table.Body>
<Table.Row>
<Table.Cell>Kate Moore</Table.Cell>
<Table.Cell>Engineer</Table.Cell>
<Table.Cell>Active</Table.Cell>
</Table.Row>
</Table.Body>
</Table.Content>
</Table.ScrollContainer>
</Table>
```
For charts, notifications, rich text editing, and other specialized needs, you'll combine HeroUI with dedicated libraries. This is a trade-off: more integration work, but you pick the best tool for each job.
## Styling Approaches
This is where the libraries diverge most sharply.
### Mantine: CSS Modules + PostCSS
Mantine uses CSS Modules for component styling. Each component has its own scoped CSS, and you customize components by targeting specific class selectors or using Mantine's `classNames` prop:
```tsx
import { Button } from "@mantine/core";
import classes from "./MyButton.module.css";
<Button classNames={{ root: classes.root, label: classes.label }}>
Click me
</Button>
```
This approach is familiar to anyone who's used CSS Modules. Styles are scoped, there's no runtime overhead, and you have direct access to override any part of a component. Mantine also supports a `styles` prop for inline style overrides and a global theme object for system-wide customization.
The downside is that you need to understand Mantine's internal class structure to customize deeply. Each component has its own set of "style names" (like `root`, `label`, `inner` for Button), and you need to reference the docs to know which ones to target.
### HeroUI: Tailwind CSS v4
HeroUI components are styled with Tailwind CSS v4 utilities. You customize components the same way you style everything else in a Tailwind project — with `className`:
```tsx
import { Button } from "@heroui/react";
<Button className="bg-gradient-to-r from-purple-500 to-pink-500 text-white shadow-lg">
Click me
</Button>
```
For component sub-parts, HeroUI's compound component pattern lets you apply classes to any section:
```tsx
import { Card } from "@heroui/react";
<Card className="max-w-md">
<Card.Header className="pb-0">
<Card.Title className="text-xl font-bold">Title</Card.Title>
<Card.Description>Subtitle here</Card.Description>
</Card.Header>
<Card.Content className="py-4">
Content goes here
</Card.Content>
<Card.Footer className="justify-end gap-2">
<Button variant="ghost">Cancel</Button>
<Button>Save</Button>
</Card.Footer>
</Card>
```
Because each sub-component accepts `className`, you don't need to learn a separate styling API or memorize internal class name structures. If you know Tailwind, you know how to customize HeroUI.
### The practical trade-off
If your project already uses Tailwind CSS, HeroUI fits like a glove — there's no second styling system to learn. If your project uses CSS Modules or plain CSS, Mantine aligns more naturally with your existing approach. Adopting HeroUI without Tailwind means adopting Tailwind, which is a separate (and significant) decision.
Both approaches produce zero runtime CSS overhead. Neither ships CSS-in-JS to the browser.
## Accessibility
This is where the difference in architectural foundations becomes most apparent.
### HeroUI: React Aria (Enterprise-Grade)
HeroUI is built on [React Aria](https://react-spectrum.adobe.com/react-aria/), Adobe's accessibility primitive library. React Aria handles screen reader support, keyboard navigation, focus management, ARIA attributes, internationalization, and interaction patterns for every component.
React Aria is one of the most thoroughly tested accessibility layers available for React. It powers Adobe's Spectrum design system and handles details like keyboard behavior, focus management, screen reader announcements, touch interactions, and internationalization. Components like date pickers, comboboxes, and tables benefit from that depth in places most teams do not want to reimplement themselves.
### Mantine: Good Built-In Accessibility
Mantine has solid accessibility built into its components. WAI-ARIA attributes, keyboard navigation, and focus management are handled for common patterns. For the vast majority of applications, Mantine's accessibility is perfectly adequate.
The gap appears in complex, interaction-heavy components. Mantine doesn't use an external accessibility layer like React Aria or Radix — it implements accessibility in-house. This means the depth of testing and edge case coverage is necessarily narrower than a dedicated accessibility library backed by a company the size of Adobe.
### When does this matter?
If you're building consumer software where basic keyboard navigation and screen reader support are sufficient, both libraries will serve you well. If you're building for government, healthcare, finance, or any domain with strict WCAG compliance requirements, HeroUI's React Aria foundation provides a higher assurance level.
## The Hooks Library
Mantine also includes a utility hooks package (`@mantine/hooks`). HeroUI focuses on component quality and leverages the broader React ecosystem for utility hooks. The hooks package covers common categories like:
- **Browser APIs**: `useClipboard`, `useFullscreen`, `useMediaQuery`, `useLocalStorage`, `useGeolocation`
- **UI patterns**: `useDisclosure`, `usePagination`, `useScrollIntoView`, `useHover`
- **Utilities**: `useDebounce`, `useThrottle`, `useInterval`, `useCounter`, `usePrevious`
- **State management**: `useListState`, `useSetState`, `useMap`, `useQueue`
For similar utility hooks, you'd use community packages like `usehooks-ts`, or React Aria's hooks (which cover accessibility-related patterns like `useFocusRing`, `usePress`, and `useSearchField`). HeroUI focuses on components and leaves general-purpose utilities to the broader ecosystem.
If your team values having a single, cohesive dependency for both components and utility hooks, Mantine's integrated approach is appealing. If you prefer picking best-in-class tools for each concern, HeroUI's focused approach works better.
## AI Tooling
This is an area where HeroUI has invested heavily and Mantine hasn't.
### HeroUI's AI developer tools
HeroUI ships three first-class integrations for AI coding assistants:
- **MCP server.** A [Model Context Protocol server](/docs/react/getting-started/mcp-server) that AI agents can query for component documentation, APIs, and usage examples. When your AI assistant is connected to this server, it can look up the exact compound component structure, available props, and correct imports for any HeroUI component in real time.
- **llms.txt.** A structured reference file at [heroui.com/llms.txt](/docs/react/getting-started/llms-txt) that gives large language models a condensed, accurate reference for the entire library. This is a standardized format that AI tools can consume to avoid hallucinating APIs.
- **Agent skills.** Pre-built [skill files](/docs/react/getting-started/agent-skills) for tools like Cursor and Claude Code that teach AI agents HeroUI's patterns — correct imports, compound component structures, styling conventions, and project scaffolding.
The result is that AI assistants have a better chance of generating current HeroUI code. They can use the correct compound component patterns (`Modal.Header`, `Card.Content`, `Table.Row`), the right import paths, and actual v3 APIs instead of guessing from mixed training data.
### Mantine's AI story
Mantine has strong AI-facing documentation too: its homepage documents `llms.txt`, skills, and `@mantine/mcp-server`. The practical difference is not "HeroUI has AI and Mantine does not." It is that HeroUI's AI context is specific to HeroUI's compound components, Tailwind v4 styling, and package API, while Mantine's context teaches Mantine's component and hooks ecosystem.
### Why this matters in 2026
Most developers use AI assistants daily. When your component library has first-class AI tooling, agents can verify current APIs before writing code. That matters for both libraries.
## Design Quality and Polish
Both libraries ship good-looking defaults, but the design sensibilities are different.
HeroUI's defaults are more opinionated and "designed." Components ship with refined animations, carefully balanced spacing, smooth transitions, and attention to micro-interactions. Buttons have subtle press states. Modals animate in with spring physics. Cards have balanced padding and shadow hierarchies. The library includes theme variants (like "glass" and "brutalism") for distinct visual identities without custom CSS.
Mantine's defaults are clean and professional but more utilitarian. Components are well-proportioned and consistent, but they're designed to be a neutral starting point rather than a finished look. If you're planning to apply significant custom styling, this is actually an advantage — there's less opinionated design to override.
The trade-off is straightforward: HeroUI looks more polished out of the box with less effort. Mantine gives you a more neutral canvas to build on.
## TypeScript Support
Both libraries have excellent TypeScript support. Components are fully typed, props interfaces are well-documented, and autocomplete works as expected in modern editors.
HeroUI's compound component pattern means TypeScript can verify the structure of your component trees:
```tsx
import { Tabs } from "@heroui/react";
<Tabs>
<Tabs.ListContainer>
<Tabs.List aria-label="Sections">
<Tabs.Tab id="profile">Profile</Tabs.Tab>
<Tabs.Tab id="settings">Settings</Tabs.Tab>
<Tabs.Indicator />
</Tabs.List>
</Tabs.ListContainer>
<Tabs.Panel id="profile">Profile content</Tabs.Panel>
<Tabs.Panel id="settings">Settings content</Tabs.Panel>
</Tabs>
```
Mantine provides equally strong types with a different API surface:
```tsx
import { Tabs } from "@mantine/core";
<Tabs defaultValue="profile">
<Tabs.List>
<Tabs.Tab value="profile">Profile</Tabs.Tab>
<Tabs.Tab value="settings">Settings</Tabs.Tab>
</Tabs.List>
<Tabs.Panel value="profile">Profile content</Tabs.Panel>
<Tabs.Panel value="settings">Settings content</Tabs.Panel>
</Tabs>
```
No meaningful advantage either way. Both libraries take TypeScript seriously.
## When to Choose Each
### Choose HeroUI if:
- You're using Tailwind CSS v4 (or want to adopt it)
- Accessibility compliance is a hard requirement (healthcare, government, finance)
- You use AI coding assistants and want first-class tooling support
- You prefer compound component APIs with structural flexibility
- You want polished, animated defaults without heavy custom theming
- Performance matters and you want a Tailwind/static CSS path
- You're building with React 19 and want good server component compatibility
### When Mantine might work
Mantine can make sense if your team uses CSS Modules and doesn't want to adopt Tailwind CSS, or if you need a very broad set of built-in components including carousels, rich text editors, and notification systems. However, that breadth means a larger dependency footprint and more API surface to maintain.
## Summary
For teams building modern React applications, HeroUI's approach — React Aria accessibility, Tailwind CSS v4, compound components, and first-party AI tooling — delivers a more maintainable and performant foundation. HeroUI's focused component set means every component is deeply tested, fully accessible, and designed to work together seamlessly. For specialized needs beyond core UI, pairing HeroUI with dedicated libraries gives you better results than relying on one library to do everything.
---
## Get Started with HeroUI
Want to see how HeroUI works in practice? The [quick start guide](/docs/react/getting-started/quick-start) gets you set up in under five minutes. Explore the [component docs](/docs/react/components) for interactive examples, or connect the [MCP server](/docs/react/getting-started/mcp-server) to your AI assistant for the best development experience.
apps/docs/content/blog/en/heroui-vs-mui.mdx
+326
View File
@@ -0,0 +1,326 @@
---
title: "HeroUI vs Material UI (MUI): A Comprehensive Comparison for 2026"
description: "Comparing HeroUI and Material UI — styling approaches, performance, accessibility, and when to choose each for your React project."
date: "2026-05-06"
author: "Junior Garcia"
authorHandle: "@jrgarciadev"
authorUrl: "https://x.com/jrgarciadev"
authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4"
tags: ["comparison", "heroui", "mui", "react"]
image: "/images/blog/heroui-vs-mui.jpg"
draft: true
---
HeroUI and Material UI (MUI) represent two different generations of React component library design. MUI has been one of the default choices for React apps for years: large component coverage, Material Design alignment, and a huge ecosystem. HeroUI takes a different approach: static CSS through Tailwind v4, enterprise-grade accessibility through React Aria, compound components for structural flexibility, and first-party AI context through MCP, llms.txt, and agent skills.
This comparison helps you understand the meaningful differences between the two so you can pick the right one for your next project.
## Architecture Overview
### HeroUI
- **Styling:** Tailwind CSS v4 with Tailwind Variants
- **Accessibility:** React Aria (Adobe)
- **Components:** <ComponentCount />+ with compound component pattern
- **Design language:** Neutral, customizable
- **React version:** Check the current peer dependency range for your installed HeroUI version
- **Server Components:** Static pieces can stay server-rendered; interactive pieces use client boundaries
- **Package:** `@heroui/react`
### Material UI (MUI)
- **Styling:** Emotion by default; Pigment CSS exists as an experimental zero-runtime path
- **Accessibility:** Custom ARIA implementation
- **Components:** 70+ (core) + MUI X premium components
- **Design language:** Material Design (Google)
- **React version:** Check the current peer dependency range for your installed MUI version
- **Server Components:** Depends on styling setup and component usage
- **Package:** `@mui/material`
## Styling: Tailwind CSS vs Emotion / Pigment CSS
This is the most consequential difference between the two libraries.
### HeroUI: Tailwind CSS v4
HeroUI uses Tailwind CSS v4 for styling. Components are styled with utility classes, and customization happens through:
- Passing Tailwind classes via `className` props
- Overriding CSS custom properties (design tokens)
- Using Tailwind Variants for structured variant customization
```tsx
<Button
variant="secondary"
className="font-semibold tracking-wide"
>
Get Started
</Button>
```
**Benefits:**
- Zero runtime CSS overhead — all styles are static
- Tailwind's utility-first approach is familiar to most React developers in 2026
- CSS custom properties enable theming without JavaScript
- Server component compatible by default
- Token customization through standard CSS `@theme`
**Trade-offs:**
- Class strings can be verbose
- You need to understand Tailwind's utility vocabulary
### MUI: Emotion by default, Pigment CSS experimental
MUI's Material UI migration docs describe Emotion as the default styling engine. Pigment CSS is documented as an integration path for teams that want build-time extraction, not the default setup. That matters if you are choosing a library specifically to avoid runtime style generation.
```tsx
<Button
variant="contained"
sx={{ fontWeight: 600, letterSpacing: '0.025em' }}
>
Get Started
</Button>
```
**Benefits:**
- Familiar `sx` prop for one-off style overrides
- Structured theming through `createTheme()`
- A mature ecosystem of examples and theme recipes
- Full JavaScript expression support in styles
**Trade-offs:**
- The `sx` prop uses a custom DSL that's distinct from standard CSS
- Theme customization requires JavaScript configuration
- Emotion adds runtime styling work in the stable setup
- Pigment CSS is not the default stable path, so adopting it requires extra due diligence
### Verdict
If you're already using Tailwind CSS, HeroUI integrates naturally. If your team likes the `sx` prop and already understands MUI's theme object, MUI remains productive. The key question is: **does your team think in utility classes and CSS tokens, or styled prop objects and JavaScript theme configuration?**
## Accessibility
### HeroUI: React Aria
HeroUI builds on React Aria, Adobe's accessibility primitive library. Every component inherits:
- Platform-aware keyboard navigation (Mac, Windows, Linux differences)
- Comprehensive screen reader support (JAWS, NVDA, VoiceOver)
- Touch interaction handling
- Right-to-left layout support
- Locale-aware formatting (dates, numbers)
- Virtual focus for large collections
- Proper focus management (trapping, restoration)
React Aria is used in Adobe's own products (Photoshop Web, Acrobat, Lightroom), which means it's tested at massive scale with real users.
### MUI: Custom Implementation
MUI implements its own accessibility layer. The quality is generally good and has improved significantly over the years:
- ARIA roles and attributes on all components
- Keyboard navigation following WAI-ARIA patterns
- Focus management in dialogs and menus
- Screen reader announcements for dynamic content
However, MUI's accessibility implementation is less comprehensive than React Aria in several areas:
- **Platform-specific behavior.** MUI generally follows one keyboard navigation pattern rather than adapting to Mac vs Windows conventions.
- **Touch interactions.** Less sophisticated than React Aria's touch handling.
- **Internationalization.** MUI's i18n is primarily about string translation. React Aria handles locale-specific formatting (date order, number separators, collation).
- **Virtual focus.** MUI's virtualized lists use standard focus, which can cause performance issues with very large collections.
### Verdict
HeroUI has a clear accessibility advantage through React Aria. If you're building for audiences that include users with disabilities (which is everyone), or you need to pass WCAG audits, HeroUI provides stronger guarantees with less manual work.
## Component Ecosystem
### HeroUI Core: <ComponentCount />+ Components
HeroUI ships <ComponentCount />+ components covering:
- Layout (Card, Surface, Separator)
- Data Display (Table, Avatar, Badge, Chip, Tag)
- Data Input (Input, Textarea, NumberField, Select, ComboBox, Autocomplete, DatePicker, DateRangePicker, ColorPicker, Slider, Switch, Checkbox, Radio)
- Navigation (Tabs, Breadcrumbs, Pagination, Link)
- Feedback (Toast, ProgressBar, ProgressCircle, Meter, Spinner, Skeleton)
- Overlay (Modal, Drawer, Popover, Tooltip, Dropdown)
- Disclosure (Accordion, Disclosure)
- Actions (Button, ToggleButton, ToggleButtonGroup)
### MUI Core: 70+ Components
MUI's core library has slightly more components. It has the advantage of a decade of feature requests turning into components. You'll find things like:
- Speed Dial
- Stepper
- Masonry
- Timeline
- Transfer List
### MUI X: Premium Components
MUI X is MUI's premium component offering:
- **Data Grid** — Sorting, filtering, column pinning, row grouping, cell editing, lazy loading, tree data. This is MUI's strongest selling point for enterprise applications.
- **Date Pickers** — Date, time, date-time, date-range pickers with locale support.
- **Charts** — Line, bar, pie, scatter, and more.
- **Tree View** — Expandable tree with lazy loading.
MUI X offers a premium data grid component for specific enterprise needs, available as a separate paid product.
### Verdict
For most applications, both libraries cover the component needs. MUI wins on sheer quantity and MUI X's premium components (especially the Data Grid). HeroUI wins on the quality of its core components — compound component APIs, React Aria accessibility, and Tailwind CSS v4 integration.
## Performance
### Bundle and runtime shape
Exact bundle size depends on your imports, bundler, and route structure, so I avoid treating one static number as universal. The architecture still matters:
HeroUI tends to stay lean because:
- Tailwind CSS styles are static (no styling runtime)
- React Aria packages are modular
- Components expose explicit compound parts
MUI can carry more styling and theme machinery because:
- The stable setup uses Emotion
- The theme system and `sx` prop are central to the API
- MUI X adds powerful but separate premium packages when you need advanced data components
### Runtime Performance
**HeroUI:** All styles are resolved at build time. No runtime style calculation, injection, or hydration. Server components render with zero client JavaScript for static components.
**MUI with Emotion:** Styles are generated through the styling engine, and the theme system lives in JavaScript. This is flexible, but it is not the same runtime profile as static CSS.
**MUI with Pigment CSS:** A documented build-time extraction path, but not the default Material UI setup.
### Server Components
**HeroUI:** Static pieces like `Card`, `Badge`, `Text`, and `Separator` can stay in server component trees. Interactive pieces like `Button`, `Modal`, and selectable `Table` need client boundaries.
**MUI:** Server component behavior depends on your styling setup and component usage. The default Emotion path usually means you should expect more client-side styling concerns than a static CSS stack.
### Verdict
HeroUI is the cleaner fit when you want Tailwind CSS and static CSS as the default. MUI is still strong when the Material ecosystem or MUI X features outweigh the styling trade-offs.
## Developer Experience
### Getting Started
**HeroUI:**
```bash
npm install @heroui/styles @heroui/react
```
Add one CSS import. Start using components. Tailwind CSS handles styling.
**MUI:**
```bash
npm install @mui/material @emotion/react @emotion/styled
```
(Pigment CSS setup is separate and experimental.)
Wrap your app with `ThemeProvider` when you need MUI theming. Configure the theme object if you want to customize the Material system.
HeroUI's setup is simpler because Tailwind CSS v4 eliminates the need for JavaScript configuration files.
### Customization
**HeroUI:** Customize with Tailwind classes and CSS custom properties. Override design tokens in CSS. Use Tailwind Variants for component-level variant customization. Everything stays in CSS/Tailwind.
**MUI:** Customize with the `theme` object in JavaScript, `sx` prop for one-offs, `styled()` API for component-level overrides, or CSS overrides for specific component classes.
### Documentation
Both libraries have comprehensive documentation.
### AI Tooling
**HeroUI** ships structured AI tooling:
- MCP server for programmatic API access
- llms.txt for AI model context
- Agent skills for AI assistant integration
This means AI coding tools can generate correct HeroUI code without hallucinating props or patterns.
**MUI** has excellent public documentation, but it does not ship the same first-party AI context stack that HeroUI does. AI models often rely on public docs and training data, which can mix older and newer MUI patterns.
## Design Language
### HeroUI: Neutral by Default
HeroUI ships with a clean, neutral design that doesn't impose a strong visual identity. Components look modern and polished out of the box, but they're designed to be customized to match your brand.
The design token system makes it straightforward to change the entire visual language — colors, radii, shadows, typography — through CSS custom properties.
### MUI: Material Design
MUI implements Google's [Material Design](https://m3.material.io/) guidelines. This gives you a recognizable, consistent design language, but it's opinionated:
- Ripple effects on interactions
- Specific elevation levels (shadows)
- Material Design color system
- Rounded rectangles with specific radii
Theming away from Material Design is possible but requires significant effort. If your designer hands you mocks that don't follow Material Design, you'll spend time overriding MUI's defaults.
### Verdict
If you want Material Design, MUI is the obvious choice. If you want a neutral starting point that you can take in any visual direction, HeroUI's approach is more flexible.
## Migration Considerations
### From MUI to HeroUI
If you're considering migrating an existing MUI project:
1. **Incremental migration is possible.** Both libraries can coexist in the same project. You can migrate page by page.
2. **Component API differences.** HeroUI uses compound components; MUI uses prop-based APIs. The migration requires rethinking component composition.
3. **Styling migration.** Moving from `sx` prop / `styled()` to Tailwind classes is the biggest effort.
4. **Accessibility.** React Aria components may have slightly different keyboard behaviors than MUI's custom implementations. Test thoroughly.
### From Other Libraries to MUI
MUI has extensive migration guides and a large community that has documented common migration patterns.
## Summary
| Dimension | HeroUI | MUI |
|-----------|--------|-----|
| Styling | Tailwind CSS v4 (static CSS) | Emotion by default; Pigment CSS experimental |
| Accessibility | React Aria (industry-leading) | Custom implementation (good, not as deep) |
| Components | <ComponentCount />+ (compound pattern) | 70+ core + MUI X premium |
| Bundle/runtime shape | Static CSS, modular packages | Mature theme system with runtime styling in the default setup |
| Server Components | Good fit for static pieces; client boundaries for interactive parts | Depends on styling setup and component usage |
| Design language | Neutral, customizable | Material Design |
| AI tooling | MCP server, llms.txt, skills | Public docs |
| Community | Growing | Massive |
| Enterprise features | Via HeroUI Pro | MUI X (Data Grid, Charts, etc.) |
| Maturity | Newer v3 architecture | Long-established ecosystem |
## When to Choose HeroUI
- You're starting a new project with Tailwind CSS
- Accessibility compliance is a priority
- You want React 19 and a Tailwind-first server component workflow
- You use AI coding tools (Cursor, Claude, etc.)
- You prefer a neutral design you can brand freely
- You prefer static CSS over runtime styling
### When MUI might work
MUI can be a reasonable choice if your team doesn't use Tailwind CSS and prefers a CSS-in-JS approach, if you need strict Material Design compliance, or if you specifically need MUI X's premium data grid. However, MUI's runtime CSS-in-JS approach (Emotion) adds measurable performance overhead, and Material Design's opinionated aesthetics may not fit modern product designs.
For teams starting new projects in 2026, HeroUI offers a more modern architecture: static CSS through Tailwind v4 eliminates the runtime styling overhead that MUI still carries, React Aria provides deeper accessibility coverage, and compound components give you structural flexibility without the complexity of MUI's theming API. HeroUI is the stronger foundation for new React applications.
## Get Started with HeroUI
- [Quick Start Guide](/docs/react/getting-started/quick-start) — Set up HeroUI in minutes
- [Component Documentation](/docs/react/components) — Full API reference
- [Theming Guide](/docs/react/getting-started/theming) — Customize the design system
- [GitHub Repository](https://github.com/heroui-inc/heroui) — Source code and issues
apps/docs/content/blog/en/heroui-vs-shadcn.mdx
+265
View File
@@ -0,0 +1,265 @@
---
title: "HeroUI vs shadcn/ui: Which React UI Library Should You Choose in 2026?"
description: "A comprehensive comparison of HeroUI and shadcn/ui — two popular React component libraries with very different approaches to styling, ownership, and developer experience."
date: "2026-05-07"
author: "Junior Garcia"
authorHandle: "@jrgarciadev"
authorUrl: "https://x.com/jrgarciadev"
authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4"
tags: ["comparison", "heroui", "shadcn", "react"]
image: "/images/blog/heroui-vs-shadcn.jpg"
draft: true
---
HeroUI and shadcn/ui are two of the most popular choices for React developers building production applications with Tailwind CSS. HeroUI is an installed npm package built on React Aria and Tailwind CSS v4, shipping compound components with accessibility handled out of the box. shadcn/ui is a copy-paste component collection built on Radix UI. Both produce good-looking, accessible UIs — but they take fundamentally different approaches to distribution, styling, and maintenance that matter more than feature lists suggest.
This isn't a "which is better" article. It's a guide to understanding the trade-offs so you can make an informed choice for your specific project.
## The TL;DR
| Feature | HeroUI | shadcn/ui |
|---------|--------|-----------|
| **Model** | Installed npm package | Copy-paste source code |
| **Styling** | Tailwind CSS v4 (static CSS) | Tailwind CSS + cva |
| **Accessibility** | React Aria (Adobe, actively maintained) | Radix UI (maintenance status uncertain) |
| **Updates** | npm update | Manual re-copy or merge |
| **Component API** | Compound components (`Card.Header`) | Flat components with variant props |
| **AI tooling** | MCP server, llms.txt, agent skills | MCP server, llms.txt, skills |
| **Code ownership** | In node_modules | In your repo |
## The Fundamental Difference
**HeroUI** is a traditional component library. You install `@heroui/react`, import components, and use them. Updates come through npm. The library team maintains the components, fixes bugs, and adds features. You customize through props, slots, and Tailwind classes.
**shadcn/ui** is a component collection. You run `npx shadcn@latest add button`, and the component source code is copied into your project. There's no runtime dependency on shadcn. You own the code completely. Updates require manually re-running the CLI or copying changes.
This distinction drives every other difference between the two.
## Architecture
### HeroUI: Installed Package
```bash
npm install @heroui/styles @heroui/react
```
```tsx
import { Button, Card, Table } from "@heroui/react";
```
HeroUI components live in `node_modules`. You import and use them like any other package. The library handles:
- Component implementation and behavior
- Accessibility (built on React Aria)
- Styling system (Tailwind Variants + CSS custom properties)
- TypeScript types
- Bug fixes and feature updates via npm
**Customization surface:** Tailwind classes through `className` props, slot-based styling via Tailwind Variants, design token overrides via CSS custom properties, and theme configuration.
### shadcn/ui: Copied Source Code
```bash
npx shadcn@latest add button
```
This creates a file like `components/ui/button.tsx` in your project. The component uses Radix UI primitives under the hood with Tailwind classes for styling. Since the code lives in your repo, you modify it directly.
**Customization surface:** Everything — you own the source code. Edit the component file directly.
## Accessibility
This is where the libraries diverge significantly.
### HeroUI: React Aria Foundation
HeroUI is built on [React Aria](https://react-spectrum.adobe.com/react-aria/), Adobe's accessibility primitive library. React Aria is one of the deepest accessibility foundations available in the React ecosystem:
- **Platform-aware keyboard navigation.** Mac, Windows, and Linux have different conventions for keyboard shortcuts. React Aria handles these differences automatically — Home/End keys, option/alt+arrow navigation, and platform-specific focus behavior.
- **Screen reader announcements.** Live regions, status messages, and announcements are handled correctly across JAWS, NVDA, and VoiceOver.
- **Touch interactions.** Long press, drag and drop, and gesture handling on mobile devices.
- **Internationalization.** Right-to-left layout support, locale-aware date/number formatting, and string collation.
- **Virtual focus.** For large collections (thousands of items), React Aria uses virtual focus to maintain performance while keeping screen readers informed.
This level of accessibility is baked into every HeroUI component. You don't configure it — it's just there.
### shadcn/ui: Radix UI Foundation
shadcn/ui builds on [Radix UI](https://www.radix-ui.com/) primitives, which provide solid accessibility:
- WAI-ARIA compliant roles and attributes
- Keyboard navigation following ARIA patterns
- Focus management with trapping and restoration
- Screen reader support
Radix is well-tested and reliable. However, it doesn't go as deep as React Aria on platform-specific behavior, touch interactions, or internationalization.
**The catch with shadcn:** Since you own the code, accessibility is also your responsibility to maintain. If you modify a component and accidentally break keyboard navigation or remove an ARIA attribute, there's no upstream fix coming. You need to catch and fix it yourself.
**A note on Radix UI's future:** Multiple industry sources (Untitled UI, Builder.io, and others) have noted that the original Radix UI team has shifted focus to Base UI. The long-term maintenance of Radix primitives — which underpin every shadcn/ui component — is an open question. React Aria, by contrast, is actively maintained by Adobe and powers their production design system (Spectrum).
### Verdict
If accessibility compliance is a hard requirement (government, healthcare, finance, education), HeroUI's React Aria foundation gives you stronger guarantees with less effort. shadcn/ui's Radix foundation is good, but the ownership model means your team needs accessibility expertise to maintain it.
## Styling
Both libraries use Tailwind CSS, but the styling architectures differ.
### HeroUI: CSS Classes + Design Tokens
HeroUI v3 ships CSS-based component styles with semantic variants and BEM-style class names. You use components through props like `variant`, then customize with Tailwind classes and CSS custom properties:
```tsx
<Button variant="secondary" size="lg">
Click me
</Button>
```
Customization happens at multiple levels:
1. **Class overrides:** Pass Tailwind classes to any component or slot
2. **Token overrides:** Change CSS custom properties to adjust the entire theme
3. **Component CSS overrides:** Override BEM classes like `.button`, `.card__header`, or `.table__row` in your CSS layer
4. **Theme-level changes:** Modify design tokens in your CSS to change the global look
HeroUI uses CSS custom properties for its design tokens, which means theming works with standard CSS — no JavaScript runtime needed.
### shadcn/ui: Direct Source Editing
shadcn/ui uses Tailwind classes directly in the component source code. Customization means editing the component file:
```tsx
// components/ui/button.tsx — you own this file
const buttonVariants = cva(
"inline-flex items-center justify-center rounded-md text-sm font-medium...",
{
variants: {
variant: {
default: "bg-primary text-primary-foreground hover:bg-primary/90",
destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
},
size: {
default: "h-10 px-4 py-2",
sm: "h-9 rounded-md px-3",
lg: "h-11 rounded-md px-8",
},
},
}
);
```
This is maximally flexible — you can change anything. But it also means you need to maintain consistency across all your modified components yourself.
### Verdict
HeroUI's approach is better for teams that want a consistent design system with minimal maintenance. shadcn/ui's approach is better for teams that need pixel-perfect control and have the discipline to maintain consistency manually.
## Component Count and Breadth
### HeroUI
HeroUI includes a broad component set, including complex pieces that are easy to get wrong:
- Calendar, DatePicker, DateRangePicker
- ComboBox, Autocomplete
- Table with sorting, selection, pagination
- ColorPicker, ColorArea, ColorSlider
- NumberField with locale-aware formatting
- Meter, ProgressBar, ProgressCircle
- Toast system
- Drawer, Modal, Popover
- Tabs, Disclosure, DisclosureGroup
Many of these are genuinely hard to build accessibly. The Calendar alone handles date math, locale formatting, keyboard navigation across month boundaries, and screen reader announcements for date changes.
### shadcn/ui
The official shadcn/ui `llms.txt` currently lists 59 component documentation entries. The collection covers most common product UI patterns:
- Dialog, Sheet, Drawer
- Command (cmdk), Combobox
- DataTable (TanStack Table wrapper)
- Calendar (react-day-picker)
- Form (React Hook Form integration)
- Charts (Recharts wrapper)
For complex components like Calendar and DataTable, shadcn/ui wraps third-party libraries rather than implementing from scratch. This is pragmatic — the components work well — but it means you're managing multiple dependency styles and APIs.
### Verdict
HeroUI has more complex, self-contained components (especially date/time, color, and number handling). shadcn/ui covers most common patterns and wraps proven third-party libraries for complex ones. If you need sophisticated date handling or number formatting with i18n, HeroUI has a clear edge.
## Developer Experience
### Installation and Setup
**HeroUI:**
```bash
npm install @heroui/styles @heroui/react
```
Add the CSS import and you're ready. One package, one import path, one set of docs.
**shadcn/ui:**
```bash
npx shadcn@latest init
npx shadcn@latest add button card table dialog
```
Each component is added individually. You choose which components to include. The CLI handles dependency resolution.
### Updates
**HeroUI:** Run `npm update @heroui/react`. All components update together. Breaking changes are documented in release notes.
**shadcn/ui:** There's no automatic update mechanism. To get improvements, you either re-run `npx shadcn@latest add` (which may overwrite your changes) or manually compare and merge upstream changes.
This is shadcn/ui's biggest practical trade-off. Ownership means responsibility for updates. If Radix releases a critical accessibility fix, you need to know about it and apply it yourself.
### AI Tooling
**HeroUI** ships first-party AI tooling:
- **MCP server** that lets AI assistants query component APIs, view source code, and access design tokens
- **llms.txt** providing structured component documentation for AI models
- **Agent skills** that teach AI assistants how to use HeroUI correctly
This means when you use HeroUI with Cursor, Claude, or other AI coding tools, the assistant can look up current component APIs instead of guessing props and imports from training data.
**shadcn/ui** also has a serious AI story. Its official docs publish `llms.txt`, skills, and an MCP server. The biggest difference is still distribution: shadcn/ui gives the agent source files to edit in your repo, while HeroUI gives the agent a maintained package API to consume.
### Verdict
HeroUI has a smoother package/update story. shadcn/ui gives you more upfront control but more ongoing maintenance. Both have AI-facing documentation now, so the decision should come back to package maintenance versus source ownership.
## When to Choose HeroUI
Choose HeroUI when:
- **Accessibility is a priority.** React Aria provides the strongest accessibility foundation available, and you don't have to maintain it yourself.
- **You want the latest stack.** HeroUI supports Tailwind CSS v4 and React 19, with static pieces that fit cleanly in server component trees.
- **You use AI coding tools and want a maintained package API.** The MCP server, llms.txt, and agent skills give AI assistants current HeroUI context.
- **You want a design system foundation.** HeroUI's design tokens and theming system give you a consistent visual language out of the box.
- **Your team doesn't have time to maintain component code.** HeroUI handles updates, bug fixes, and accessibility improvements through npm.
### When shadcn/ui might work
shadcn/ui can make sense if your company policy requires all component code to live in your repository rather than in node_modules, or if your design diverges so heavily from any library's defaults that you need to modify component internals. Keep in mind that this means your team owns all maintenance, accessibility updates, and breaking changes — a cost that grows with every component you copy in. Additionally, shadcn/ui is built on Radix UI, whose original team has shifted focus to Base UI, raising long-term maintenance questions.
## Can You Use Both?
Yes. Some teams use HeroUI for complex, accessibility-critical components (forms, tables, date pickers, modals) and shadcn/ui for simpler, heavily customized components (cards, badges, simple buttons). Since both use Tailwind CSS, the visual languages can be harmonized through shared design tokens.
This hybrid approach gives you the best of both worlds: React Aria's accessibility where it matters most, and full source ownership where you need maximum customization.
## Conclusion
For most teams building products — SaaS apps, internal tools, consumer applications — HeroUI's approach delivers better results: maintained accessibility through React Aria, consistent updates via npm, a cohesive design system, and AI tooling that works out of the box. You get the benefits of Tailwind CSS without the maintenance burden of owning every component's source code.
## Get Started
- [HeroUI Quick Start Guide](/docs/react/getting-started/quick-start)
- [HeroUI Component Documentation](/docs/react/components)
- [React Component Libraries Compared](/blog/react-component-library-comparison)
- [GitHub Repository](https://github.com/heroui-inc/heroui)
apps/docs/content/blog/en/react-component-library-comparison.mdx
+257
View File
@@ -0,0 +1,257 @@
---
title: "React Component Libraries Compared: A Developer's Guide for 2026"
description: "An in-depth comparison of React component libraries — styling approaches, accessibility standards, bundle sizes, and developer experience. Updated for 2026."
date: "2026-05-09"
author: "Junior Garcia"
authorHandle: "@jrgarciadev"
authorUrl: "https://x.com/jrgarciadev"
authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4"
tags: ["react", "comparison", "ui-libraries"]
image: "/images/blog/react-component-library-comparison.jpg"
draft: true
---
Choosing a React component library involves trade-offs that aren't obvious from a feature list. Styling approach determines how easy customization will be. Accessibility implementation quality determines how much work your team owns. Runtime shape affects Core Web Vitals. Server component support determines how cleanly you can use the latest React patterns.
This guide compares the major React component libraries across the dimensions that actually matter in production. Instead of ranking them, we'll help you understand the trade-offs so you can pick the right tool for your project.
## The Landscape in 2026
The React component library ecosystem has converged around a few key trends:
- **Tailwind CSS momentum.** Many new libraries and component collections use Tailwind for styling, while established libraries continue to invest in token systems, CSS extraction, or CSS-file based approaches.
- **Accessibility as table stakes.** Libraries built on React Aria have raised the bar. "Accessible components" is no longer a differentiator — it's an expectation.
- **Server component compatibility.** Libraries must work with React Server Components and the Next.js App Router, or they'll lose relevance.
- **AI tooling integration.** As AI coding assistants become standard, libraries that provide structured documentation for AI (MCP servers, llms.txt, agent skills) have an adoption advantage. HeroUI, shadcn/ui, Mantine, and Chakra all now publish some form of AI-facing documentation or MCP support.
## Styling Approaches Compared
The styling system is the single most impactful decision in choosing a component library. It affects every customization, every theme change, and every developer who touches the code.
### Tailwind CSS (Utility-First)
**Used by:** HeroUI, shadcn/ui, Headless UI, Park UI
Tailwind CSS applies styles through utility classes directly in markup. Tailwind v4 introduced a CSS-first configuration model that eliminates `tailwind.config.js` in favor of CSS `@theme` directives.
**Pros:**
- No runtime CSS overhead — styles are extracted at build time
- Utility classes are predictable and composable
- Works with any build system and framework
- Large ecosystem of plugins, tools, and developer familiarity
- Server component compatible by default
**Cons:**
- Class strings can get long for complex components
- Requires learning the utility class vocabulary
- Theming requires understanding Tailwind's token system
### CSS-in-JS (Runtime)
**Used by:** MUI (Emotion), Chakra UI v2 (Emotion), styled-components
Runtime CSS-in-JS generates styles at runtime using JavaScript. The styles are injected into the document head when components render.
**Pros:**
- Dynamic styles based on props and state
- Co-located styles with component logic
- Full JavaScript expression support in styles
**Cons:**
- Runtime performance overhead (style generation, injection, hydration)
- Not compatible with React Server Components
- SSR complexity (must extract styles during server rendering)
- Larger bundle size due to the styling runtime
**Current status:** Many CSS-in-JS libraries are exploring static extraction or more structured recipes. MUI documents Emotion as the default styling engine and Pigment CSS as an integration path. Chakra's current theming system is built around the Panda CSS API.
### Zero-Runtime CSS-in-JS
**Used by:** Pigment CSS experiments, Panda CSS-based systems, and other compiled styling tools
Zero-runtime approaches compile CSS-in-JS syntax to static CSS at build time. You write styles using a JS/TS API, but the output is plain CSS with no runtime overhead.
**Pros:**
- Familiar CSS-in-JS authoring experience
- No runtime performance overhead
- Server component compatible
- Static extraction means better caching
**Cons:**
- Build-time compilation adds to dev server startup and build times
- Less dynamic than runtime CSS-in-JS
- Tooling is newer and less mature than runtime alternatives
- Migration from runtime CSS-in-JS can be painful
### CSS Modules
**Used by:** Mantine
CSS Modules scope class names to the component file, preventing style conflicts without runtime overhead.
**Pros:**
- Zero runtime overhead
- Familiar CSS syntax
- Scoping prevents conflicts automatically
- Works with any build tool
**Cons:**
- Styles live in separate files, breaking co-location
- Less dynamic than JS-based approaches
- Theming requires CSS custom properties or build-time variables
### Unstyled (Bring Your Own)
**Used by:** Radix UI, React Aria, Ark UI, Headless UI
Unstyled libraries provide behavior and accessibility without any visual styling.
**Pros:**
- No design opinions to override
- Works with any styling system
- Minimal bundle size
- Maximum customization flexibility
**Cons:**
- You must build and maintain all visual styles yourself
- Longer time-to-first-component
- Consistency relies on your team's discipline
### Which Approach Wins?
| Project Type | Recommended Approach |
|-------------|---------------------|
| New project with Tailwind | HeroUI, shadcn/ui |
| Enterprise with Material Design | MUI / MUI X |
| Custom design system from scratch | React Aria + Tailwind, Radix UI + Tailwind |
| Maximum component breadth | Mantine (CSS Modules) |
| Cross-framework consistency | Ark UI (unstyled) |
## Accessibility Deep Dive
Accessibility isn't a checkbox — it's a spectrum. Here's how the major primitive layers compare.
### React Aria (Adobe)
React Aria is one of the deepest accessibility foundations available for React:
- **Keyboard navigation** with platform-specific conventions (Mac vs Windows vs Linux behavior differences)
- **Screen reader announcements** with appropriate ARIA live regions
- **Touch interactions** including long press, drag and drop, and gesture handling
- **Internationalization** including right-to-left layout, date/number formatting, and collation
- **Focus management** including focus trapping, focus restoration, and virtual focus for large collections
**Libraries built on React Aria:** HeroUI, Adobe React Spectrum
### Radix UI
Radix provides high-quality accessibility for common interactive patterns:
- **Keyboard navigation** following WAI-ARIA patterns
- **Focus management** with focus trapping and restoration
- **Screen reader support** with proper ARIA attributes and announcements
- **Typeahead** in listboxes and menus
**Libraries built on Radix:** shadcn/ui
### Accessibility Comparison Table
| Feature | React Aria | Radix UI | Zag.js | Custom (Mantine, MUI) |
|---------|-----------|----------|--------|----------------------|
| WAI-ARIA compliance | Comprehensive | Strong | Strong | Varies |
| Keyboard navigation | Platform-aware | Standard | Standard | Standard |
| Screen reader testing | Extensive | Good | Good | Moderate |
| RTL support | Built-in | Partial | Built-in | Varies |
| Touch interactions | Comprehensive | Basic | Basic | Basic |
| Virtual focus (large lists) | Yes | No | No | No |
| i18n (dates, numbers) | Yes | No | No | Varies |
## Bundle Size and Performance
I don't like publishing one universal bundle-size table because it goes stale quickly and depends on your bundler, import style, route splitting, and which components you use. The safer way to compare libraries is by runtime shape:
| Runtime factor | What to check |
|----------------|---------------|
| Styling runtime | Does the library calculate/inject styles in the browser, or ship static CSS? |
| Component granularity | Can you import only the pieces you use? |
| Route splitting | Can heavy pieces like charts, data grids, and rich editors be isolated to specific routes? |
| Server compatibility | Can static layout pieces stay in server component trees? |
| Third-party dependencies | Are complex widgets pulling charting, date, table, or editor packages into shared bundles? |
For a real app, run your bundle analyzer against the routes you care about. Marketing pages and dashboards have very different budgets.
## Server Component Compatibility
| Library | Server component fit | Client boundary approach |
|---------|----------------------|--------------------------|
| HeroUI | Good for static pieces | Interactive components need client boundaries |
| shadcn/ui | You control it | Depends on the copied component and its primitives |
| MUI | Depends on styling setup | Emotion/theming often pushes work client-side |
| Chakra UI | Depends on component and style props | Interactive and style-heavy usage needs client testing |
| Mantine | CSS Modules are server-friendly | Interactive components still need client boundaries |
| Ant Design | More client-heavy | Test route by route |
## AI and Tooling Integration
As AI coding assistants become standard tools, how well a component library works with AI matters for developer productivity.
| Library | Verified AI-facing support |
|---------|----------------------------|
| HeroUI | MCP server, llms.txt, agent skills |
| shadcn/ui | MCP server, llms.txt, skills |
| Mantine | MCP server, llms.txt / llms-full.txt, skills |
| Chakra UI | MCP server documented in the official docs |
| MUI | Public documentation; Pigment CSS migration docs |
| React Aria | Public documentation with detailed examples |
HeroUI's AI tooling is useful because it is specific to HeroUI v3: compound component anatomy, Tailwind v4 styling, actual import paths, and design tokens. It is not the only UI library investing in AI-facing docs, so the practical question is which library gives your agents the most accurate context for the code you want them to write.
## Decision Framework
### Start with your constraints
1. **Do you need Material Design compliance?** → MUI
2. **Do you need the same library across React, Vue, and Solid?** → Ark UI
3. **Do you want the broadest all-in-one component and hooks toolkit?** → Mantine
4. **Are you building a custom design system from scratch?** → HeroUI (React Aria foundation with compound components)
### Then optimize for your priorities
| Priority | Best Choice |
|----------|------------|
| Modern stack (Tailwind v4, React 19, RSC) | HeroUI |
| Maximum code ownership | shadcn/ui |
| Largest community and ecosystem | MUI |
| Best accessibility foundation | HeroUI (React Aria) |
| AI-assisted development with HeroUI-specific patterns | HeroUI (MCP server, llms.txt, skills) |
| Enterprise data components | MUI X or Ant Design |
| Fastest prototyping | Chakra UI (though style props trade-off is JSX verbosity at scale) |
| Most components per install | Mantine (though breadth comes with larger bundles) |
### Red flags to watch for
- **No tree-shaking.** If importing one component pulls in the entire library, your bundle will suffer.
- **Runtime CSS-in-JS in 2026.** The ecosystem has moved on. Runtime style generation is a performance tax.
- **No TypeScript.** JavaScript-only libraries will feel increasingly outdated.
- **No server component support.** If every component requires `"use client"`, you're missing significant performance benefits.
- **Abandoned maintenance.** Check the last release date and open issue count.
## Conclusion
The React component library ecosystem is mature enough that there's no truly bad choice among the major options:
- **HeroUI** optimizes for modern React, Tailwind v4, React Aria accessibility, and HeroUI-specific AI tooling.
- **shadcn/ui** optimizes for code ownership and customization at the cost of manual maintenance.
- **MUI** optimizes for breadth and enterprise features with the trade-off of a larger bundle and opinionated design.
- **Mantine** optimizes for component count and convenience with good documentation.
- **Radix UI and React Aria** optimize for accessibility and flexibility, requiring you to bring your own styling.
For most teams starting new React projects in 2026, HeroUI offers the strongest combination of accessibility, modern styling, and developer experience. Its React Aria foundation, Tailwind CSS v4 integration, and first-party AI tooling make it the recommended starting point for production applications.
## Further Reading
- [12 Best React UI Component Libraries in 2026](/blog/best-react-ui-component-libraries) — Detailed profiles of each library
- [What is a Design System?](/blog/what-is-a-design-system) — Understanding the bigger picture
- [HeroUI Getting Started](/docs/react/getting-started/quick-start) — Try HeroUI in your next project
- [HeroUI Component Documentation](/docs/react/components) — Full API reference
apps/docs/content/blog/en/what-is-a-design-system.mdx
+279
View File
@@ -0,0 +1,279 @@
---
title: "What is a Design System? A Complete Guide for 2026"
description: "Learn what a design system is, why your team needs one, and how React component libraries like HeroUI make building them easier."
date: "2026-05-08"
author: "Junior Garcia"
authorHandle: "@jrgarciadev"
authorUrl: "https://x.com/jrgarciadev"
authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4"
tags: ["design-system", "react", "ui"]
image: "/images/blog/what-is-a-design-system.jpg"
draft: true
---
A design system is a collection of reusable components, design tokens, patterns, and guidelines that help teams build consistent user interfaces at scale. It's both a product and a process — the components your engineers use to build features, the tokens your designers reference in Figma, and the documentation that keeps everyone aligned.
If you've ever shipped a feature where the button padding didn't match the rest of the app, or where one modal used a 16px border radius and another used 12px, you've felt the absence of a design system. This guide explains what a design system actually is, why your team probably needs one, and how modern React component libraries make building them far more practical than it was five years ago.
## Design System vs. Component Library vs. Style Guide
These three terms get used interchangeably, but they're different things at different levels of abstraction.
### Style Guide
A style guide documents visual standards: colors, typography, spacing, iconography, and logo usage. It tells you *what things should look like* but doesn't give you tools to build them.
**Example:** "Primary buttons use the accent token, 14px semibold text, 8px vertical padding, 16px horizontal padding, and a 12px radius."
### Component Library
A component library is a collection of reusable UI components. It tells you *how to build things* but doesn't necessarily explain *when to use them* or *why they look that way*.
**Example:** A `Button` component in a package like `@heroui/react` that accepts `size` and semantic `variant` props.
### Design System
A design system combines both and adds process, documentation, and governance. It tells you *what things should look like*, *how to build them*, *when to use which pattern*, and *how to contribute changes*.
**Components of a design system:**
| Layer | Purpose | Example |
|-------|---------|---------|
| **Design tokens** | Shared values for color, spacing, typography, shadows | `--accent: oklch(0.65 0.24 260)` |
| **Component library** | Reusable UI building blocks | `<Button>`, `<Card>`, `<Table>` |
| **Patterns** | Repeatable solutions to common design problems | Form validation pattern, empty state pattern |
| **Documentation** | Usage guidelines, do's and don'ts, accessibility notes | "Use destructive buttons only for irreversible actions" |
| **Contribution model** | Process for proposing, reviewing, and shipping changes | RFC process, design review, release cycle |
## Why Your Team Needs a Design System
### Consistency at scale
Without a design system, every developer makes independent decisions about spacing, colors, and interaction patterns. With five developers, you might get five different approaches. With fifty, you get chaos.
A design system centralizes these decisions. When the primary color changes, you update one token and it propagates everywhere. When the team agrees on a new modal pattern, it's documented and available for everyone.
### Speed
Design systems save time by eliminating redundant work. Instead of designing and building a data table from scratch for every feature, teams use the existing Table component and focus on the data model and business logic that's unique to their feature.
The speed gains compound over time. The first team to use the design system saves a little. The twentieth team saves a lot.
### Quality
Components in a design system are built once and improved continuously. Accessibility, keyboard navigation, screen reader support, responsive behavior, and edge cases are handled in the component library rather than reimplemented (with varying quality) across features.
### Shared vocabulary
Design systems give teams a common language. When a designer says "use a Card with a flat variant," the developer knows exactly what component and props to use. This reduces back-and-forth between design and engineering.
## Anatomy of a Modern Design System
### Design Tokens
Design tokens are the atomic values that define your visual language. They're the single source of truth for colors, spacing, typography, shadows, borders, and motion.
In modern systems, tokens are typically expressed as CSS custom properties:
```css
@theme {
--color-accent: var(--accent);
--color-background: var(--background);
--color-foreground: var(--foreground);
--radius-md: calc(var(--radius) * 0.75);
--shadow-surface: var(--surface-shadow);
}
```
Tailwind CSS v4 uses a CSS-first token system with `@theme`, which HeroUI builds on. HeroUI's shipped theme maps real CSS variables such as `--accent`, `--background`, `--foreground`, `--radius`, and `--surface-shadow` into Tailwind utilities.
**Why tokens matter:**
- **Theming.** Change your brand color in one place and it updates everywhere — components, backgrounds, borders, hover states.
- **Dark mode.** Define a separate token set for dark mode; components adapt automatically.
- **Multi-brand.** Run the same components with different token sets for different brands.
- **Consistency.** No more guessing whether the correct gray is `#f3f4f6` or `#f4f5f7`.
### Component Architecture
Modern component libraries use two main patterns:
#### Compound Components
Compound components expose sub-components that compose together:
```tsx
<Card>
<Card.Header>
<h3>Title</h3>
</Card.Header>
<Card.Content>
<p>Content goes here</p>
</Card.Content>
<Card.Footer>
<Button>Action</Button>
</Card.Footer>
</Card>
```
HeroUI uses this pattern. Each sub-component is independently styleable, and you can omit parts you don't need. The parent component manages shared state (like selection in a RadioGroup) while children control their own rendering.
#### Monolithic Components
Monolithic components accept all configuration through props:
```tsx
<Card
title="Title"
description="Content goes here"
footer={<Button>Action</Button>}
/>
```
This is simpler for basic use cases but becomes rigid when you need custom layouts, conditional rendering, or non-standard markup.
**Which is better?** Compound components scale better for design systems because they give consuming teams more control without requiring library changes. When a team needs to add an icon between the title and description, they just add it — no new prop needed.
### Accessibility Layer
The best design systems build accessibility into the foundation layer, not the component layer. This means using a primitive library like React Aria or Radix UI that handles:
- ARIA attributes and roles
- Keyboard navigation patterns
- Focus management (trapping, restoration, virtual focus)
- Screen reader announcements
- Touch and pointer interactions
- Right-to-left layout support
HeroUI builds on [React Aria](https://react-spectrum.adobe.com/react-aria/), one of the most comprehensive accessibility primitive libraries available for React. This means HeroUI components — from Button to Calendar to ComboBox — inherit battle-tested accessibility behavior.
## Building a Design System with React
### Option 1: Adopt a Component Library
The fastest path to a design system is adopting an existing component library and extending it. This gives you:
- Pre-built components with accessibility handled
- A token system you can customize
- Documentation and examples
- Community support and ongoing maintenance
**Best for:** Teams that want to move fast and don't have unique design requirements that existing libraries can't accommodate.
**Recommended libraries:**
| Library | Styling | Best For |
|---------|---------|----------|
| HeroUI | Tailwind CSS v4 | Modern stack, accessibility, AI tooling |
| shadcn/ui | Tailwind CSS | Maximum code ownership |
| MUI | Emotion / `sx` prop, with Pigment CSS experimental | Material Design, enterprise |
| Mantine | CSS Modules | Maximum component breadth |
### Option 2: Build on Primitives
If you need a fully custom design language, build your components on top of accessibility primitives:
- **React Aria** — Most comprehensive accessibility primitives. Used by HeroUI.
- **Radix UI** — Excellent accessibility, popular composition patterns. Used by shadcn/ui.
- **Ark UI** — State machine-based, works across React/Vue/Solid.
**Best for:** Teams with dedicated design system engineers and unique design requirements.
### Option 3: Extend and Customize
Many teams start by adopting a library (option 1) and gradually extend it. HeroUI supports this through:
- **CSS-based component classes** for predictable customization
- **CSS custom properties** for token overrides
- **Compound component pattern** for structural customization
- **Theme system** for global visual changes
This hybrid approach gives you the speed of a pre-built library with the flexibility to diverge where your product needs it.
## Design Tokens in Practice
### Setting Up Tokens with Tailwind CSS v4
Tailwind v4 lets you define design tokens directly in CSS:
```css
@import "tailwindcss";
@import "@heroui/styles";
:root {
--accent: oklch(0.6204 0.195 253.83);
--accent-foreground: var(--snow);
--radius: 0.5rem;
--surface-shadow:
0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06),
0 0 1px 0 rgba(0, 0, 0, 0.06);
}
```
These tokens become Tailwind utilities automatically:
```tsx
<div className="rounded-md bg-accent shadow-surface">
<p className="text-accent-foreground">Styled with HeroUI tokens</p>
</div>
```
### Token Organization
Organize tokens in layers:
1. **Primitive tokens** — Raw values that do not change between themes (`--snow`, `--eclipse`)
2. **Semantic tokens** — Theme-aware values (`--background`, `--foreground`, `--accent`, `--surface`)
3. **Computed Tailwind tokens** — Utility-facing values generated in `@theme` (`--color-accent`, `--color-background`, `--radius-md`)
HeroUI uses this layered approach. You can override at any level — change the primary color globally, adjust the card radius specifically, or create an entirely new theme.
## Common Pitfalls
### Over-engineering early
Don't build a design system before you need one. If you're a team of three building an MVP, adopting a component library is enough. The system should emerge from patterns you discover, not be designed upfront.
### Treating it as a one-time project
A design system is a product, not a project. It needs ongoing investment — new components, bug fixes, documentation updates, and user support. If you build it and walk away, it'll be outdated within months.
### Ignoring the developer experience
If your design system is hard to use, developers will work around it. Prioritize:
- Clear, searchable documentation
- Copy-pasteable code examples
- Sensible defaults that work without configuration
- Escape hatches for edge cases
### Forgetting accessibility
Bolting accessibility onto an existing component library is painful and often incomplete. Choose a foundation (React Aria, Radix UI) that handles accessibility from the start.
## How HeroUI Fits In
HeroUI provides the component library and token system layers of a design system:
- **<ComponentCount />+ components** built on React Aria with compound component APIs
- **Tailwind CSS v4 tokens** for colors, spacing, radii, and typography
- **Theme system** with light/dark mode and custom themes
- **AI tooling** (MCP server, llms.txt, agent skills) for developer productivity
You still need to add your own patterns, documentation, and governance on top — but the engineering-heavy parts (accessible components, a token system, theme support) are handled.
## Getting Started
1. **Audit your current UI.** Identify inconsistencies — different button styles, inconsistent spacing, duplicate components. These are the problems a design system solves.
2. **Adopt a component library.** Start with HeroUI or another library that matches your stack. Customize the tokens to match your brand.
3. **Document your patterns.** As your team builds features, document the patterns that emerge — how you handle empty states, form validation, loading states, error messages.
4. **Establish governance.** Decide how new components get proposed, reviewed, and shipped. Keep it lightweight at first.
5. **Iterate.** A design system is never done. Measure adoption, collect feedback, and improve continuously.
## Further Reading
- [HeroUI Quick Start Guide](/docs/react/getting-started/quick-start) — Get started with HeroUI's component library
- [HeroUI Theming Guide](/docs/react/getting-started/theming) — Customize design tokens and themes
- [React Component Libraries Compared](/blog/react-component-library-comparison) — Compare your options
- [Component Documentation](/docs/react/components) — Explore HeroUI's component library
apps/docs/content/blog/en/why-choose-heroui-for-your-design-system.mdx
+305
View File
@@ -0,0 +1,305 @@
---
title: "Why Choose HeroUI for Your Design System"
description: "Why choose HeroUI: React Aria accessibility, Tailwind CSS v4 styling, compound components, and AI-native tooling for production React apps."
date: "2026-05-17"
author: "Junior Garcia"
authorHandle: "@jrgarciadev"
authorUrl: "https://x.com/jrgarciadev"
authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4"
tags: ["heroui", "design-system", "react", "ui-libraries"]
image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-og_2x.jpg"
darkImage: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-og-black_2x.jpg"
---
Most React component libraries solve the same problem: stop rebuilding buttons. But design systems fail at a different stage — when the library you chose can't flex to your product's needs, when accessibility is an afterthought bolted on after launch, or when your AI coding assistant hallucinates props that don't exist.
HeroUI combines [React Aria](https://react-spectrum.adobe.com/react-aria/) for accessibility, [Tailwind CSS v4](https://tailwindcss.com/) for styling, and a compound component API that gives you structural control without prop sprawl. This post explains the concrete reasons to choose it as the foundation of your design system.
## The Stack
| Layer | Technology | Why |
|-------|-----------|-----|
| **Accessibility** | React Aria (Adobe) | Industry-leading WCAG primitives, actively maintained |
| **Styling** | Tailwind CSS v4 | Static CSS, zero runtime, design tokens via `@theme` |
| **Component API** | Compound components | `Card.Header`, `Modal.Body` — structural control without prop sprawl |
| **Types** | TypeScript | Full type coverage, generic props, strict mode compatible |
| **AI tooling** | MCP server, llms.txt, agent skills | AI assistants get current APIs, not stale training data |
| **Cross-platform** | HeroUI Native (React Native) | Same design system on web and mobile — no other open library does this |
## Accessibility That's Actually Enterprise-Grade
Every HeroUI component is built on [React Aria](https://react-spectrum.adobe.com/react-aria/), Adobe's accessibility primitive library. This isn't a marketing checkbox — React Aria is the deepest accessibility foundation available for React, and it powers Adobe's own production design system (Spectrum) across Photoshop Web, Acrobat, and Lightroom.
What React Aria handles that most libraries don't:
- **Platform-aware keyboard navigation.** Mac, Windows, and Linux have different conventions for Home/End, option/alt+arrow, and focus behavior. React Aria adapts automatically.
- **Screen reader announcements.** Live regions, status messages, and dynamic content announcements work correctly across JAWS, NVDA, and VoiceOver.
- **Touch interactions.** Long press, drag and drop, and gesture handling on mobile — not just click events.
- **Internationalization.** Right-to-left layouts, locale-aware date/number formatting, and string collation for 30+ languages.
- **Virtual focus.** For collections with thousands of items, React Aria maintains performance while keeping screen readers informed.
This matters because accessibility compliance isn't optional in 2026. Government, healthcare, finance, and education all require WCAG conformance. HeroUI gives you that conformance as a default, not an upgrade.
### React Aria vs Radix UI
Many popular libraries (shadcn/ui, Park UI) are built on Radix UI. Radix is solid, but the original team has shifted focus to Base UI, and the long-term maintenance of Radix primitives is an open question. React Aria is actively maintained by Adobe — a company that depends on it for their own products.
## Tailwind CSS v4 Native
HeroUI doesn't use Tailwind as a compatibility layer — it's built for Tailwind CSS v4 from the ground up.
**What this means in practice:**
- **Zero runtime CSS overhead.** All styles are static CSS, resolved at build time. No CSS-in-JS computation, no style injection, no hydration cost.
- **Design tokens via CSS custom properties.** Your theme lives in standard CSS `@theme` directives, not JavaScript configuration objects. Change a token and every component updates.
- **Utility-first customization.** Override any component with `className` — the same Tailwind workflow you use for everything else in your project.
- **Smaller output.** Tailwind v4's new engine produces less CSS. Combined with HeroUI's modular imports, your production bundle stays lean.
```tsx
<Button variant="secondary" className="font-semibold tracking-wide">
Get Started
</Button>
<Card className="max-w-md shadow-lg">
<Card.Header className="pb-0">
<Card.Title className="text-xl font-bold">Dashboard</Card.Title>
</Card.Header>
<Card.Content className="py-4">
Your metrics here
</Card.Content>
</Card>
```
If your team already uses Tailwind, HeroUI integrates without introducing a second styling system. If you don't use Tailwind yet, adopting it is a separate decision — but one that most React teams in 2026 have already made.
## Compound Component API
HeroUI uses compound components — a pattern where parent components expose sub-components through dot notation. This is the same approach used by Radix UI, and it scales far better than prop-based APIs for complex UIs.
```tsx
<Modal>
<Button>Open</Button>
<Modal.Backdrop>
<Modal.Container>
<Modal.Dialog>
<Modal.Header>
<Modal.Heading>Confirm</Modal.Heading>
</Modal.Header>
<Modal.Body>Are you sure?</Modal.Body>
<Modal.Footer>
<Button variant="ghost">Cancel</Button>
<Button>Confirm</Button>
</Modal.Footer>
</Modal.Dialog>
</Modal.Container>
</Modal.Backdrop>
</Modal>
```
**Why this matters for design systems:**
- **Structural control.** Reorder, omit, or insert custom elements between component parts. No fighting the library's internal layout.
- **Slot-level styling.** Apply `className` to any sub-component independently. Style `Card.Header` differently from `Card.Footer` without CSS overrides.
- **TypeScript verification.** The compiler checks your component tree structure — wrong nesting gets caught at build time, not in production.
- **Readable JSX.** The hierarchy of your component maps directly to the visual hierarchy of your UI. New team members can read the code and understand the layout.
## <ComponentCount />+ Components
HeroUI ships <ComponentCount />+ components with <ExampleCount />+ documented examples. The library covers the full product UI surface:
- **Data input** — Input, Textarea, NumberField, Select, ComboBox, Autocomplete, DatePicker, DateRangePicker, ColorPicker, Slider, Switch, Checkbox, Radio
- **Data display** — Table (sorting, selection, pagination), Avatar, Badge, Chip, Tag, Skeleton
- **Layout** — Card, Surface, Separator, Fieldset
- **Navigation** — Tabs, Breadcrumbs, Pagination, Link
- **Feedback** — Toast, ProgressBar, ProgressCircle, Meter, Spinner
- **Overlay** — Modal, Drawer, Popover, Tooltip, Dropdown, AlertDialog
- **Disclosure** — Accordion, Disclosure
- **Actions** — Button, ToggleButton, ToggleButtonGroup
Complex components like Calendar, DatePicker, ColorPicker, and Table are self-contained — they handle date math, locale formatting, keyboard navigation, and screen reader announcements internally. These are genuinely hard to build accessibly, and HeroUI ships them as maintained, tested primitives.
## AI-Native Tooling
Most developers use AI coding assistants daily. The quality of generated code depends on whether the AI has accurate context for your component library — or is guessing from stale training data.
HeroUI ships four first-party integrations:
### MCP Server
A [Model Context Protocol server](/docs/react/getting-started/mcp-server) that AI agents can query for component documentation, APIs, source code, and design tokens. Connect it to Cursor, Claude Code, Windsurf, or any MCP-compatible editor.
When an AI assistant has access to the MCP server, it can look up the exact compound component structure, available props, and correct imports for any HeroUI component — instead of hallucinating.
[Learn how to set up the MCP Server →](/docs/react/getting-started/mcp-server)
### llms.txt
A structured reference file at [heroui.com/llms.txt](/docs/react/getting-started/llms-txt) that gives LLMs a condensed, accurate reference for the entire library. This is a standardized format that AI tools consume to avoid generating deprecated patterns.
[Learn more about llms.txt →](/docs/react/getting-started/llms-txt)
### Agent Skills
Pre-built [skill files](/docs/react/getting-started/agent-skills) for Cursor, Claude Code, and other AI tools that teach agents HeroUI's conventions — correct imports, compound component patterns, styling approaches, and project scaffolding.
[Learn how to install Agent Skills →](/docs/react/getting-started/agent-skills)
### AGENTS.md
An [AGENTS.md file](/docs/react/getting-started/agents-md) that provides repository-level context for AI coding agents. It describes the project structure, coding conventions, and component patterns so agents understand your codebase from the first prompt.
[Learn about AGENTS.md →](/docs/react/getting-started/agents-md)
**The result:** AI assistants generate correct HeroUI v3 code with the right compound component patterns, import paths, and Tailwind classes. This matters because incorrect AI output costs more time to debug than it saves to generate.
## The Ecosystem
### HeroUI Pro
[HeroUI Pro](https://heroui.com/pro) extends the base library with app-level components and templates:
- **AppLayout, Sidebar, Navbar** — Full application shell with responsive behavior
- **DataGrid** — Dense data tables with typed columns, sorting, and filtering
- **KPI, NumberValue, TrendChip** — Dashboard metric components
- **LineChart, BarChart** — Data visualization
- **Sheet, CommandMenu** — Advanced overlay patterns
- **Templates** — Dashboard, finance, chat, and email app starting points
Pro is a paid product — use it when you need app infrastructure, not just UI components.
### HeroUI Native
<DocsImage
src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/heroui-native-og-light-1.webp"
darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/heroui-native-og-dark-1.webp"
alt="HeroUI Native - React Native components"
/>
HeroUI is the only open design system that delivers the same component quality across both web and mobile. [HeroUI Native](/docs/native/getting-started) brings the same design tokens, compound component API, and accessibility standards to React Native — leveraging each platform's native APIs instead of wrapping web views.
This means teams building cross-platform products can share a single design system across React (web) and React Native (mobile) without compromising on either platform. Same visual language, same component patterns, same theming tokens — but native rendering on each side.
No other open-source React component library offers this. MUI, shadcn/ui, Chakra UI, and Mantine are web-only. If your product ships on both web and mobile, HeroUI is the only design system that covers both from the same foundation.
### Figma Kit
<DocsImage
src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/blog/community-figma-preview-light.png"
darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/blog/community-figma-preview-dark.png"
alt="HeroUI Figma Kit"
/>
The [HeroUI Figma Kit (v3)](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3) keeps design and code in sync. Components in Figma match the React implementation, so designers and developers work from the same source of truth.
### Storybook
Every component has [Storybook stories](https://storybook-v3.heroui.com/) showing all variants, states, and compositions. Use it for visual testing, design review, and documentation.
### Community
HeroUI isn't new — we've been building it for over 5 years, starting from v1 (originally NextUI). The community has grown steadily: 29.3K+ GitHub stars, 9K+ Discord members, and thousands of discussions, community answers, and issues resolved every week.
- [GitHub](https://github.com/heroui-inc/heroui) — Source code, issues, and discussions
- [Discord](https://discord.gg/heroui) — 9K+ members, community support and announcements
- [X / Twitter](https://x.com/hero_ui) — Updates and releases
### Backed by Y Combinator
HeroUI is venture-backed, including [Y Combinator](https://www.ycombinator.com/companies/heroui). This means a dedicated full-time team, long-term maintenance commitments, and the resources to keep shipping. When you adopt a component library, you're betting on its future — HeroUI is built to be around for the long run.
## Design Quality Out of the Box
HeroUI ships with refined defaults that look polished without custom theming:
- **Smooth animations.** Buttons have subtle press states. Modals animate with spring physics. Accordions expand with natural easing.
- **Balanced spacing tokens.** Consistent padding, margins, and gaps across all components follow a mathematical scale.
- **Shadow hierarchy.** Elevation levels that work in both light and dark mode without manual adjustment.
- **Theme variants.** Built-in support for visual identities like glass, brutalism, and neutral — switchable through design tokens.
The design token system uses CSS custom properties, so theming is standard CSS:
```css
@theme {
--color-primary: oklch(0.6 0.25 260);
--radius-field: 0.5rem;
--shadow-surface: 0 1px 3px rgba(0, 0, 0, 0.08);
}
```
Change tokens globally and every component updates. No JavaScript theme objects, no provider wrappers, no runtime overhead.
Want to make HeroUI yours in a few clicks? The [Theme Builder](/themes) lets you customize colors, typography, radius, and spacing visually — then export a ready-to-use CSS theme for your project.
## Ready in Two Steps
Most component libraries require configuration files, provider wrappers, theme objects, and plugin setup before you can render your first component. HeroUI doesn't. The entire setup is two steps:
**1. Install:**
```bash
npm i @heroui/styles @heroui/react
```
**2. Add one line to your CSS:**
```css
@import "tailwindcss";
@import "@heroui/styles"; /* That's it */
```
Now use any component — no `ThemeProvider`, no `ChakraProvider`, no `MantineProvider`, no configuration objects:
```tsx
import { Button, Card } from "@heroui/react";
export default function Page() {
return (
<Card>
<Card.Content>
<Button>Click me</Button>
</Card.Content>
</Card>
);
}
```
That's the entire setup. No wrapping your app in providers, no theme configuration files, no runtime setup. Install, import one CSS line, and start building. See the [Quick Start guide](/docs/react/getting-started/quick-start) to get running in under five minutes.
## Server Components
HeroUI is designed for the React Server Components model:
- **Static components** (`Card`, `Badge`, `Text`, `Separator`, `Avatar`) stay in server component trees with zero client JavaScript.
- **Interactive components** (`Button`, `Modal`, `Table`, `Select`) use client boundaries — clearly documented per component.
- **No provider required** — no client-side context that forces your entire tree into a client boundary.
This means your pages ship less JavaScript by default. Static layouts render on the server. Interactive widgets hydrate only where needed.
## Considerations
HeroUI takes a focused approach: instead of shipping every possible component, we prioritize depth, accessibility, and quality for the components teams use most. For specialized needs like rich text editing, drag-and-drop, or charting, we recommend pairing HeroUI with dedicated libraries that excel at those specific problems — this gives you better results than relying on a single library to handle everything.
HeroUI is built for Tailwind CSS v4. If your team is already using Tailwind, adoption is seamless. If you're on a different styling approach, the switch to Tailwind is a separate but worthwhile investment in modern CSS tooling.
## Who Should Use HeroUI
HeroUI is a strong fit if you're building:
- **SaaS applications** — Forms, tables, overlays, and navigation with React Aria accessibility
- **Dashboards and admin panels** — Data-dense layouts with HeroUI Pro components
- **E-commerce storefronts** — Performant, accessible, SEO-friendly component rendering
- **Marketing sites and landing pages** — Polished defaults without runtime CSS overhead
- **Cross-platform products** — Same design system on web (React) and mobile (React Native) with HeroUI Native
- **Any React / Next.js project** that values accessibility, Tailwind CSS integration, and AI-assisted development
## Get Started
```bash
npm install @heroui/styles @heroui/react
```
- [Quick Start Guide](/docs/react/getting-started/quick-start) — Set up in under five minutes
- [Component Documentation](/docs/react/components) — Full API reference with live examples
- [Theming Guide](/docs/react/getting-started/theming) — Customize the design system
- [MCP Server](/docs/react/getting-started/mcp-server) — Connect your AI coding assistant
- [GitHub Repository](https://github.com/heroui-inc/heroui) — Source code and issues
apps/docs/content/docs/cn/meta.json
+3
View File
@@ -0,0 +1,3 @@
{
"pages": ["react", "native"]
}
apps/docs/content/docs/cn/native/components/(buttons)/button.mdx
+391
View File
@@ -0,0 +1,391 @@
---
title: Button 按钮
description: 按下时触发操作的交互组件。
links:
source_native: button/button.tsx
styles_native: button/button.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/button-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/button-docs-dark.mp4"
/>
## 导入
```tsx
import { Button } from 'heroui-native';
```
## 结构
```tsx
<Button>
<Button.Label>...</Button.Label>
</Button>
```
- **Button**：主容器，负责按压交互、动画与变体。字符串子节点会渲染为标签，也可使用复合子组件自定义布局。
- **Button.Label**：按钮文字，继承父级 Button 上下文中的尺寸与变体样式。
## 用法
### 基础用法
`Button` 可直接传入字符串子节点，会自动渲染为标签。
```tsx
<Button>基础按钮</Button>
```
### 使用复合子组件
使用 `Button.Label` 显式控制标签部分。
```tsx
<Button>
<Button.Label>点我</Button.Label>
</Button>
```
### 与图标组合
将图标与文字组合，增强可读性。
```tsx
<Button>
<Icon name="add" size={20} />
<Button.Label>添加项目</Button.Label>
</Button>
<Button>
<Button.Label>下载</Button.Label>
<Icon name="download" size={18} />
</Button>
```
### 仅图标
使用 `isIconOnly` 创建方形纯图标按钮。
```tsx
<Button isIconOnly>
<Icon name="heart" size={18} />
</Button>
```
### 尺寸
通过三种尺寸控制按钮大小。
```tsx
<Button size="sm">小</Button>
<Button size="md">中</Button>
<Button size="lg">大</Button>
```
### 变体
提供七种视觉变体，用于不同强调层级。
```tsx
<Button variant="primary">主要</Button>
<Button variant="secondary">次要</Button>
<Button variant="tertiary">第三级</Button>
<Button variant="outline">描边</Button>
<Button variant="ghost">幽灵</Button>
<Button variant="danger">危险</Button>
<Button variant="danger-soft">柔和危险</Button>
```
### 反馈变体
`feedbackVariant` 控制渲染哪些按压反馈效果：
- `'scale-highlight'`（默认）：内置缩放 + 高亮遮罩
- `'scale-ripple'`：内置缩放 + 水波纹遮罩
- `'scale'`：仅内置缩放（无遮罩）
- `'none'`：无任何反馈动画
```tsx
{/* 缩放 + 高亮（默认） */}
<Button feedbackVariant="scale-highlight">高亮效果</Button>
{/* 缩放 + 水波纹 */}
<Button feedbackVariant="scale-ripple">水波纹效果</Button>
{/* 仅缩放 */}
<Button feedbackVariant="scale">仅缩放</Button>
{/* 无反馈 */}
<Button feedbackVariant="none">无反馈</Button>
```
### 自定义动画
`animation` 控制各子动画，其结构取决于 `feedbackVariant`。
```tsx
{/* 自定义缩放与高亮（默认 feedbackVariant） */}
<Button
animation={{
scale: { value: 0.97 },
highlight: {
backgroundColor: { value: '#3b82f6' },
opacity: { value: [0, 0.2] },
},
}}
>
自定义高亮
</Button>
{/* 自定义缩放与水波纹 */}
<Button
feedbackVariant="scale-ripple"
animation={{
scale: { value: 0.97 },
ripple: {
backgroundColor: { value: '#3b82f6' },
opacity: { value: [0, 0.3, 0] },
},
}}
>
自定义水波纹
</Button>
```
### 关闭部分子动画
将某个子动画设为 `false` 即可单独关闭：
```tsx
{/* 关闭缩放，保留高亮 */}
<Button animation={{ scale: false }}>无缩放</Button>
{/* 关闭高亮，保留缩放 */}
<Button animation={{ highlight: false }}>无高亮</Button>
{/* 两者都关 */}
<Button animation={{ scale: false, highlight: false }}>无动画</Button>
```
### 关闭全部动画
使用 `animation={false}` 关闭所有反馈，或使用 `animation="disable-all"` 级联关闭：
```tsx
<Button animation={false}>已禁用动画</Button>
<Button animation="disable-all">全部禁用（级联）</Button>
```
### 加载态与 Spinner
配合 Spinner 展示加载状态。
```tsx
const themeColorAccentForeground = useThemeColor('accent-foreground');
<Button
layout={LinearTransition.springify()}
variant="primary"
onPress={() => {
setIsDownloading(true);
setTimeout(() => {
setIsDownloading(false);
}, 3000);
}}
isIconOnly={isDownloading}
className="self-center"
>
{isDownloading ? (
<Spinner entering={FadeIn.delay(50)} color={themeColorAccentForeground} />
) : (
'立即下载'
)}
</Button>;
```
### 使用 LinearGradient 自定义背景
通过绝对定位元素添加渐变背景。使用 `feedbackVariant="none"` 关闭默认高亮遮罩，或使用 `feedbackVariant="scale-ripple"` 自定义水波纹。
```tsx
import { Button, PressableFeedback } from 'heroui-native';
import { LinearGradient } from 'expo-linear-gradient';
import { StyleSheet } from 'react-native';
{/* 无反馈遮罩的渐变 */}
<Button feedbackVariant="none">
<LinearGradient
colors={['#9333ea', '#ec4899']}
start={{ x: 0, y: 0 }}
end={{ x: 1, y: 0 }}
style={StyleSheet.absoluteFill}
/>
<Button.Label className="text-white font-bold">渐变</Button.Label>
</Button>
{/* 带自定义水波纹的渐变 */}
<Button
feedbackVariant="scale-ripple"
animation={{
ripple: {
backgroundColor: { value: 'white' },
opacity: { value: [0, 0.5, 0] },
},
}}
>
<LinearGradient
colors={['#0d9488', '#ec4899']}
start={{ x: 0, y: 0 }}
end={{ x: 1, y: 0 }}
style={StyleSheet.absoluteFill}
/>
<Button.Label className="text-white font-bold" pointerEvents="none">
带水波纹的渐变
</Button.Label>
</Button>
```
## 示例
```tsx
import { Button, useThemeColor } from 'heroui-native';
import { Ionicons } from '@expo/vector-icons';
import { View } from 'react-native';
export default function ButtonExample() {
const [
themeColorAccentForeground,
themeColorAccentSoftForeground,
themeColorDangerForeground,
themeColorDefaultForeground,
] = useThemeColor([
'accent-foreground',
'accent-soft-foreground',
'danger-foreground',
'default-foreground',
]);
return (
<View className="gap-4 p-4">
<Button variant="primary">
<Ionicons name="add" size={20} color={themeColorAccentForeground} />
<Button.Label>添加项目</Button.Label>
</Button>
<View className="flex-row gap-4">
<Button size="sm" isIconOnly>
<Ionicons name="heart" size={16} color={themeColorAccentForeground} />
</Button>
<Button size="sm" variant="secondary" isIconOnly>
<Ionicons
name="bookmark"
size={16}
color={themeColorAccentSoftForeground}
/>
</Button>
<Button size="sm" variant="danger" isIconOnly>
<Ionicons name="trash" size={16} color={themeColorDangerForeground} />
</Button>
</View>
<Button variant="tertiary">
<Button.Label>了解更多</Button.Label>
<Ionicons
name="chevron-forward"
size={18}
color={themeColorDefaultForeground}
/>
</Button>
</View>
);
}
```
更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/button.tsx>)。
## API 参考
### Button
`Button` 继承 [PressableFeedback](./pressable-feedback) 的全部属性（`animation` 除外，已重新定义），并增加按钮专用属性。
| prop | type | default | description |
| ----------------- | --------------------------------------------------------------------------------------------- | ------------------- | -------------------------------------------------------------- |
| `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'outline' \| 'ghost' \| 'danger' \| 'danger-soft'` | `'primary'` | 按钮视觉变体 |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 按钮尺寸 |
| `isIconOnly` | `boolean` | `false` | 是否为仅图标按钮（方形比例） |
| `feedbackVariant` | `'scale-highlight' \| 'scale-ripple' \| 'scale' \| 'none'` | `'scale-highlight'` | 决定渲染哪些反馈效果 |
| `animation` | `ButtonAnimation` | - | 动画配置（结构取决于 `feedbackVariant`） |
继承属性（含 `isDisabled`、`className`、`children` 及所有 Pressable 属性）见 [PressableFeedback API 参考](./pressable-feedback#api-reference)。
#### ButtonAnimation
`animation` 是按 `feedbackVariant` 区分的联合类型，遵循 `AnimationRoot` 控制流：
- `true` 或 `undefined`：使用默认动画
- `false` 或 `"disabled"`：关闭所有反馈动画
- `"disable-all"`：级联关闭所有动画（含子复合部件）
- `object`：自定义子动画配置（见下）
**当 `feedbackVariant="scale-highlight"`（默认）时：**
| prop | type | default | description |
| ----------- | ---------------------------------------- | ------- | ------------------------------------------------------------ |
| `scale` | `PressableFeedbackScaleAnimation` | - | 缩放动画配置（`false` 为关闭） |
| `highlight` | `PressableFeedbackHighlightAnimation` | - | 高亮遮罩配置（`false` 为关闭） |
| `state` | `'disabled' \| 'disable-all' \| boolean` | - | 在保留配置的同时控制动画状态（运行时切换） |
**当 `feedbackVariant="scale-ripple"` 时：**
| prop | type | default | description |
| -------- | ---------------------------------------- | ------- | ------------------------------------------------------------ |
| `scale` | `PressableFeedbackScaleAnimation` | - | 缩放动画配置（`false` 为关闭） |
| `ripple` | `PressableFeedbackRippleAnimation` | - | 水波纹遮罩配置（`false` 为关闭） |
| `state` | `'disabled' \| 'disable-all' \| boolean` | - | 在保留配置的同时控制动画状态（运行时切换） |
**当 `feedbackVariant="scale"` 时：**
| prop | type | default | description |
| ------- | ---------------------------------------- | ------- | ------------------------------------------------------------ |
| `scale` | `PressableFeedbackScaleAnimation` | - | 缩放动画配置（`false` 为关闭） |
| `state` | `'disabled' \| 'disable-all' \| boolean` | - | 在保留配置的同时控制动画状态（运行时切换） |
**当 `feedbackVariant="none"` 时：**
仅接受字符串 `'disable-all'`。所有反馈效果均被禁用。
动画子类型（`PressableFeedbackScaleAnimation`、`PressableFeedbackHighlightAnimation`、`PressableFeedbackRippleAnimation`）详见 [PressableFeedback API 参考](./pressable-feedback#api-reference)。
### Button.Label
| prop | type | default | description |
| -------------- | ----------------- | ------- | ------------------------------------- |
| `children` | `React.ReactNode` | - | 作为标签渲染的内容 |
| `className` | `string` | - | 额外 CSS 类 |
| `...TextProps` | `TextProps` | - | 支持全部标准 Text 属性 |
## Hooks
### useButton
用于读取 Button 上下文，返回尺寸、变体与禁用状态。
```tsx
import { useButton } from 'heroui-native';
const { size, variant, isDisabled } = useButton();
```
#### 返回值
| property | type | description |
| ------------ | --------------------------------------------------------------------------------------------- | ------------------------------ |
| `size` | `'sm' \| 'md' \| 'lg'` | 按钮尺寸 |
| `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'outline' \| 'ghost' \| 'danger' \| 'danger-soft'` | 按钮视觉变体 |
| `isDisabled` | `boolean` | 是否禁用 |
**说明：** 必须在 `Button` 内使用；在按钮上下文外调用会抛错。
apps/docs/content/docs/cn/native/components/(buttons)/close-button.mdx
+119
View File
@@ -0,0 +1,119 @@
---
title: CloseButton 关闭按钮
description: 用于关闭对话框、模态框或收起内容的按钮组件。
links:
source_native: close-button/close-button.tsx
styles_native: close-button/close-button.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/close-button-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/close-button-docs-dark.mp4"
/>
## 导入
```tsx
import { CloseButton } from 'heroui-native';
```
## 用法
### 基础用法
CloseButton 渲染带默认样式的关闭图标按钮。
```tsx
<CloseButton />
```
### 自定义图标颜色
通过 `iconProps` 自定义图标颜色。
```tsx
<CloseButton iconProps={{ color: themeColorDanger }} />
<CloseButton iconProps={{ color: themeColorAccent }} />
```
### 自定义图标尺寸
通过 `iconProps` 调整图标大小。
```tsx
<CloseButton iconProps={{ size: 24 }} />
```
### 自定义子节点
用自定义内容替换默认关闭图标。
```tsx
<CloseButton>
<CustomIcon />
</CloseButton>
```
### 禁用态
禁用按钮以禁止交互。
```tsx
<CloseButton isDisabled />
```
## 示例
```tsx
import { CloseButton, useThemeColor } from 'heroui-native';
import { Ionicons } from '@expo/vector-icons';
import { View } from 'react-native';
import { withUniwind } from 'uniwind';
const StyledIonicons = withUniwind(Ionicons);
export default function CloseButtonExample() {
const themeColorForeground = useThemeColor('foreground');
const themeColorDanger = useThemeColor('danger');
return (
<View className="flex-1 px-5 items-center justify-center">
<View className="flex-row items-center gap-4">
<CloseButton />
<CloseButton iconProps={{ color: themeColorDanger }} />
<CloseButton>
<StyledIonicons
name="close-circle"
size={28}
color={themeColorForeground}
/>
</CloseButton>
<CloseButton isDisabled />
</View>
</View>
);
}
```
更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/close-button.tsx)。
## API 参考
### CloseButton
CloseButton 继承 [Button](./button) 的全部属性。默认 `variant='tertiary'`、`size='sm'`、`isIconOnly=true`。
| prop | type | default | description |
| ----------- | ---------------------- | ------- | ------------------------------------------------ |
| `iconProps` | `CloseButtonIconProps` | - | 自定义关闭图标属性 |
| `children` | `React.ReactNode` | - | 自定义内容，替换默认关闭图标 |
`isDisabled`、`className`、`animation`、`feedbackVariant` 以及所有 Pressable 相关继承属性见 [Button API 参考](./button#api-reference)。
#### CloseButtonIconProps
| prop | type | default | description |
| ------- | -------- | ---------------------- | ----------------- |
| `size` | `number` | `20` | 图标尺寸 |
| `color` | `string` | Uses theme muted color | 图标颜色 |
apps/docs/content/docs/cn/native/components/(buttons)/link-button.mdx
+164
View File
@@ -0,0 +1,164 @@
---
title: LinkButton 链接按钮
description: 幽灵样式按钮，无高亮按压反馈，适合行内链接式交互。
links:
source_native: link-button/link-button.tsx
styles_native: link-button/link-button.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/link-button-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/link-button-docs-dark.mp4"
/>
## 导入
```tsx
import { LinkButton } from 'heroui-native';
```
## 结构
```tsx
<LinkButton>
<LinkButton.Label>...</LinkButton.Label>
</LinkButton>
```
- **LinkButton**：根级可按压容器。内部渲染 `variant="ghost"` 的 `Button`，并强制关闭高亮反馈；使用者无法覆盖上述行为。
- **LinkButton.Label**：链接按钮文字，继承父级上下文中的尺寸与变体样式。
## 用法
### 基础用法
行内链接风格文字，响应按压。
```tsx
<LinkButton onPress={handlePress}>了解更多</LinkButton>
```
### 尺寸
使用 `size` 控制文字尺寸。
```tsx
<LinkButton size="sm">
小
</LinkButton>
<LinkButton size="md">
中
</LinkButton>
<LinkButton size="lg">
大
</LinkButton>
```
### 禁用状态
禁用后不可交互。
```tsx
<LinkButton isDisabled>已禁用的链接</LinkButton>
```
### 自定义样式
在根与 `Label` 上使用 `className`。
```tsx
<LinkButton className="px-2">
<LinkButton.Label className="text-accent underline">
样式化链接
</LinkButton.Label>
</LinkButton>
```
### 与正文混排
与普通文字混排，用于条款、政策或上下文导航。
```tsx
<View className="flex-row flex-wrap">
<Text className="text-sm text-muted">我同意 </Text>
<LinkButton size="sm" onPress={handleTermsPress}>
<LinkButton.Label className="text-accent">
服务条款
</LinkButton.Label>
</LinkButton>
<Text className="text-sm text-muted"> 与 </Text>
<LinkButton size="sm" onPress={handlePrivacyPress}>
<LinkButton.Label className="text-accent">隐私政策</LinkButton.Label>
</LinkButton>
</View>
```
## 示例
```tsx
import { Button, Checkbox, ControlField, LinkButton } from 'heroui-native';
import React from 'react';
import { Alert, View, Text } from 'react-native';
export default function LinkButtonExample() {
const [isAgreed, setIsAgreed] = React.useState(false);
const handleTermsPress = () => Alert.alert('条款', '跳转至服务条款');
const handlePrivacyPress = () =>
Alert.alert('隐私', '跳转至隐私政策');
return (
<View className="flex-1 px-5 items-center justify-center">
<View className="w-full max-w-xs gap-6">
<ControlField
isSelected={isAgreed}
onSelectedChange={setIsAgreed}
className="items-start"
>
<ControlField.Indicator>
<Checkbox className="mt-0.5" />
</ControlField.Indicator>
<View className="flex-row flex-wrap flex-1">
<Text className="text-sm text-muted">我同意 </Text>
<LinkButton size="sm" onPress={handleTermsPress}>
<LinkButton.Label className="text-accent">
服务条款
</LinkButton.Label>
</LinkButton>
<Text className="text-sm text-muted"> 与 </Text>
<LinkButton size="sm" onPress={handlePrivacyPress}>
<LinkButton.Label className="text-accent">
隐私政策
</LinkButton.Label>
</LinkButton>
</View>
</ControlField>
<Button isDisabled={!isAgreed}>注册</Button>
</View>
</View>
);
}
```
更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/link-button.tsx>)。
## API 参考
### LinkButton
继承 [Button](./button#button) 的全部属性，**除 `variant` 外**（内部固定为 `ghost`）。
**内部强制行为：**
| override | value | description |
| ----------- | ------------ | ---------------------------------------- |
| `variant` | `ghost` | 始终为 ghost，不可修改 |
| `highlight` | `false` | 高亮反馈关闭，不可修改 |
| `className` | `h-auto p-0` | 移除默认按钮高度与内边距 |
### LinkButton.Label
与 [Button.Label](./button#buttonlabel) 等价，属性相同。
apps/docs/content/docs/cn/native/components/(collections)/menu.mdx
+811
View File
@@ -0,0 +1,811 @@
---
title: Menu 菜单
description: 浮动上下文菜单，支持定位、选择分组与多种呈现方式。
icon: updated
links:
source_native: menu/menu.tsx
styles_native: menu/menu.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/menu-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/menu-docs-dark.mp4"
/>
## 导入
```tsx
import { Menu, SubMenu } from 'heroui-native';
```
## 结构
```tsx
<Menu>
<Menu.Trigger>...</Menu.Trigger>
<Menu.Portal>
<Menu.Overlay />
<Menu.Content presentation="popover">
<Menu.Close />
<Menu.Label>...</Menu.Label>
<Menu.Group>
<Menu.Item>
<Menu.ItemIndicator />
<Menu.ItemTitle>...</Menu.ItemTitle>
<Menu.ItemDescription>...</Menu.ItemDescription>
</Menu.Item>
</Menu.Group>
<SubMenu>
<SubMenu.Trigger textValue="...">
<SubMenu.TriggerIndicator />
...
</SubMenu.Trigger>
<SubMenu.Content>
<Menu.Item>...</Menu.Item>
<Menu.Item>...</Menu.Item>
</SubMenu.Content>
</SubMenu>
</Menu.Content>
</Menu.Portal>
</Menu>
```
- **Menu**：主容器，管理开闭状态与定位，并向子组件提供上下文。
- **Menu.Trigger**：可点击元素，用于切换菜单显隐。
- **Menu.Portal**：在 Portal 层渲染菜单内容，叠于其他内容之上。
- **Menu.Overlay**：可选背景遮罩，用于捕获外部点击并关闭菜单。
- **Menu.Content**：菜单内容容器；两种呈现：带定位与碰撞检测的浮动 Popover，或底部抽屉式 Bottom Sheet。
- **Menu.Close**：关闭按钮，按下后关闭菜单。
- **Menu.Label**：菜单内的非交互分区标题。
- **Menu.Group**：对菜单项分组，可选选择模式（无 / 单选 / 多选）。
- **Menu.Item**：可按压菜单项，带按压动画反馈；可独立使用或置于 Group 内参与选择。
- **Menu.ItemTitle**：菜单项主标题文本。
- **Menu.ItemDescription**：菜单项次要说明文本。
- **Menu.ItemIndicator**：菜单项选中指示（对勾或圆点）。
- **SubMenu**：子菜单根容器，管理展开/收起状态并为子级提供动画上下文。
- **SubMenu.Trigger**：可按压行，切换子菜单开闭；样式与普通菜单项一致。
- **SubMenu.TriggerIndicator**：动画 V 形图标（默认 chevron-right），随子菜单开闭旋转；放在 `SubMenu.Trigger` 内。
- **SubMenu.Content**：绝对定位容器，子菜单开闭时带动画高度变化；其内放置 `Menu.Item` 等。
## 用法
### 基础用法
Menu 通过复合部件组成浮动上下文菜单。
```tsx
<Menu>
<Menu.Trigger>...</Menu.Trigger>
<Menu.Portal>
<Menu.Overlay />
<Menu.Content presentation="popover" width={220}>
<Menu.Item>
<Menu.ItemTitle>View Profile</Menu.ItemTitle>
</Menu.Item>
<Menu.Item>
<Menu.ItemTitle>Settings</Menu.ItemTitle>
</Menu.Item>
</Menu.Content>
</Menu.Portal>
</Menu>
```
### 带副标题
在标题旁为菜单项添加次要说明文字。
```tsx
<Menu>
<Menu.Trigger>...</Menu.Trigger>
<Menu.Portal>
<Menu.Overlay />
<Menu.Content presentation="popover" width={260}>
<Menu.Item className="items-start">
<View className="flex-1">
<Menu.ItemTitle>New file</Menu.ItemTitle>
<Menu.ItemDescription>Create a new file</Menu.ItemDescription>
</View>
</Menu.Item>
<Menu.Item className="items-start">
<View className="flex-1">
<Menu.ItemTitle>Copy link</Menu.ItemTitle>
<Menu.ItemDescription>Copy the file link</Menu.ItemDescription>
</View>
</Menu.Item>
</Menu.Content>
</Menu.Portal>
</Menu>
```
### 单选
使用 `Menu.Group` 并设置 `selectionMode="single"`，同一时间仅允许选中一项。
```tsx
const [theme, setTheme] = useState<Set<MenuKey>>(() => new Set(['system']));
<Menu>
<Menu.Trigger>...</Menu.Trigger>
<Menu.Portal>
<Menu.Overlay />
<Menu.Content presentation="popover" width={180}>
<Menu.Label>Appearance</Menu.Label>
<Menu.Group
selectionMode="single"
selectedKeys={theme}
onSelectionChange={setTheme}
>
<Menu.Item id="light">
<Menu.ItemIndicator />
<Menu.ItemTitle>Light</Menu.ItemTitle>
</Menu.Item>
<Menu.Item id="dark">
<Menu.ItemIndicator />
<Menu.ItemTitle>Dark</Menu.ItemTitle>
</Menu.Item>
<Menu.Item id="system">
<Menu.ItemIndicator />
<Menu.ItemTitle>System</Menu.ItemTitle>
</Menu.Item>
</Menu.Group>
</Menu.Content>
</Menu.Portal>
</Menu>;
```
### 多选
使用 `selectionMode="multiple"` 可同时选中多项。
```tsx
const [textStyles, setTextStyles] = useState<Set<MenuKey>>(
() => new Set(['bold', 'italic'])
);
<Menu>
<Menu.Trigger>...</Menu.Trigger>
<Menu.Portal>
<Menu.Overlay />
<Menu.Content presentation="popover" width={250}>
<Menu.Label>Text Style</Menu.Label>
<Menu.Group
selectionMode="multiple"
selectedKeys={textStyles}
onSelectionChange={setTextStyles}
>
<Menu.Item id="bold">
<Menu.ItemIndicator />
<Menu.ItemTitle>Bold</Menu.ItemTitle>
</Menu.Item>
<Menu.Item id="italic">
<Menu.ItemIndicator />
<Menu.ItemTitle>Italic</Menu.ItemTitle>
</Menu.Item>
<Menu.Item id="underline">
<Menu.ItemIndicator />
<Menu.ItemTitle>Underline</Menu.ItemTitle>
</Menu.Item>
</Menu.Group>
</Menu.Content>
</Menu.Portal>
</Menu>;
```
### 子菜单
在 `Menu.Content` 内嵌套 `SubMenu`，按压后展开更多项。
```tsx
<Menu>
<Menu.Trigger asChild>
<Button variant="secondary">Editor Menu</Button>
</Menu.Trigger>
<Menu.Portal>
<Menu.Overlay />
<Menu.Content presentation="popover" width={240}>
<Menu.Item>
<Menu.ItemTitle>New Space</Menu.ItemTitle>
</Menu.Item>
<SubMenu>
<SubMenu.Trigger textValue="Focus">
<SubMenu.TriggerIndicator />
<Text className="flex-1 text-base font-medium text-foreground">
Focus
</Text>
</SubMenu.Trigger>
<SubMenu.Content>
<Menu.Item>
<Menu.ItemTitle>Zen Mode</Menu.ItemTitle>
</Menu.Item>
<Menu.Item>
<Menu.ItemTitle>Reader Mode</Menu.ItemTitle>
</Menu.Item>
<Menu.Item>
<Menu.ItemTitle>Lock Tab</Menu.ItemTitle>
</Menu.Item>
</SubMenu.Content>
</SubMenu>
<Menu.Item>
<Menu.ItemTitle>Heading 1</Menu.ItemTitle>
</Menu.Item>
</Menu.Content>
</Menu.Portal>
</Menu>
```
### 危险变体
对破坏性操作在菜单项上使用 `variant="danger"`。
```tsx
<Menu>
<Menu.Trigger>...</Menu.Trigger>
<Menu.Portal>
<Menu.Overlay />
<Menu.Content presentation="popover" width={220}>
<Menu.Item>
<Menu.ItemTitle>Edit</Menu.ItemTitle>
</Menu.Item>
<Menu.Item variant="danger">
<Menu.ItemTitle>Delete</Menu.ItemTitle>
</Menu.Item>
</Menu.Content>
</Menu.Portal>
</Menu>
```
### 方位
控制菜单相对触发器出现的位置。
```tsx
<Menu>
<Menu.Trigger>...</Menu.Trigger>
<Menu.Portal>
<Menu.Overlay />
<Menu.Content presentation="popover" placement="right" width={200}>
<Menu.Item>
<Menu.ItemTitle>Option A</Menu.ItemTitle>
</Menu.Item>
<Menu.Item>
<Menu.ItemTitle>Option B</Menu.ItemTitle>
</Menu.Item>
</Menu.Content>
</Menu.Portal>
</Menu>
```
### Bottom Sheet 呈现
使用 `presentation="bottom-sheet"` 以底部抽屉形式展示菜单内容。
```tsx
<Menu presentation="bottom-sheet">
<Menu.Trigger>...</Menu.Trigger>
<Menu.Portal>
<Menu.Overlay />
<Menu.Content presentation="bottom-sheet">
<Menu.Item>
<Menu.ItemTitle>Option A</Menu.ItemTitle>
</Menu.Item>
<Menu.Item>
<Menu.ItemTitle>Option B</Menu.ItemTitle>
</Menu.Item>
</Menu.Content>
</Menu.Portal>
</Menu>
```
### 圆点指示器
在 `Menu.ItemIndicator` 上使用 `variant="dot"` 显示实心圆点，而非对勾。
```tsx
<Menu>
<Menu.Trigger>...</Menu.Trigger>
<Menu.Portal>
<Menu.Overlay />
<Menu.Content presentation="popover" width={180}>
<Menu.Group
selectionMode="single"
selectedKeys={alignment}
onSelectionChange={setAlignment}
>
<Menu.Item id="left">
<Menu.ItemIndicator variant="dot" />
<Menu.ItemTitle>Left</Menu.ItemTitle>
</Menu.Item>
<Menu.Item id="center">
<Menu.ItemIndicator variant="dot" />
<Menu.ItemTitle>Center</Menu.ItemTitle>
</Menu.Item>
<Menu.Item id="right">
<Menu.ItemIndicator variant="dot" />
<Menu.ItemTitle>Right</Menu.ItemTitle>
</Menu.Item>
</Menu.Group>
</Menu.Content>
</Menu.Portal>
</Menu>
```
## 示例
```tsx
import type { MenuKey } from 'heroui-native';
import { Button, Menu, Separator } from 'heroui-native';
import { useState } from 'react';
import { Text, View } from 'react-native';
export default function MenuExample() {
const [textStyles, setTextStyles] = useState<Set<MenuKey>>(
() => new Set(['bold', 'italic'])
);
const [alignment, setAlignment] = useState<Set<MenuKey>>(
() => new Set(['left'])
);
return (
<Menu>
<Menu.Trigger asChild>
<Button variant="secondary">Styles</Button>
</Menu.Trigger>
<Menu.Portal>
<Menu.Overlay />
<Menu.Content presentation="popover" width={250}>
<Menu.Label className="mb-1">Text Style</Menu.Label>
<Menu.Group
selectionMode="multiple"
selectedKeys={textStyles}
onSelectionChange={setTextStyles}
>
<Menu.Item id="bold">
<Menu.ItemIndicator />
<Menu.ItemTitle>Bold</Menu.ItemTitle>
<Text className="text-sm text-muted">⌘ B</Text>
</Menu.Item>
<Menu.Item id="italic">
<Menu.ItemIndicator />
<Menu.ItemTitle>Italic</Menu.ItemTitle>
<Text className="text-sm text-muted">⌘ I</Text>
</Menu.Item>
<Menu.Item id="underline">
<Menu.ItemIndicator />
<Menu.ItemTitle>Underline</Menu.ItemTitle>
<Text className="text-sm text-muted">⌘ U</Text>
</Menu.Item>
</Menu.Group>
<Separator className="mx-2 my-2 opacity-75" />
<Menu.Label className="mb-1">Text Alignment</Menu.Label>
<Menu.Group
selectionMode="single"
selectedKeys={alignment}
onSelectionChange={setAlignment}
>
<Menu.Item id="left">
<Menu.ItemIndicator variant="dot" />
<Menu.ItemTitle>Left</Menu.ItemTitle>
</Menu.Item>
<Menu.Item id="center">
<Menu.ItemIndicator variant="dot" />
<Menu.ItemTitle>Center</Menu.ItemTitle>
</Menu.Item>
<Menu.Item id="right">
<Menu.ItemIndicator variant="dot" />
<Menu.ItemTitle>Right</Menu.ItemTitle>
</Menu.Item>
</Menu.Group>
</Menu.Content>
</Menu.Portal>
</Menu>
);
}
```
更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/menu.tsx>)。
## API 参考
### Menu
| prop | type | default | description |
| --------------- | ----------------------------- | ----------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | - | 菜单内容 |
| `presentation` | `'popover' \| 'bottom-sheet'` | `'popover'` | 菜单内容的呈现方式 |
| `isOpen` | `boolean` | - | 受控开闭状态 |
| `isDefaultOpen` | `boolean` | - | 非受控：首次渲染时是否打开 |
| `isDisabled` | `boolean` | - | 是否禁用菜单 |
| `animation` | `MenuRootAnimation` | - | 菜单根级动画配置 |
| `onOpenChange` | `(open: boolean) => void` | - | 开闭状态变化时触发 |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部标准属性 |
#### MenuRootAnimation
菜单根组件的动画配置，可为：
- `"disable-all"`：关闭所有动画（含子级）
- `true` 或 `undefined`：使用默认动画
### Menu.Trigger
| prop | type | default | description |
| ------------------- | ----------------- | ------- | ------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 触发器内容 |
| `className` | `string` | - | 触发器额外 class |
| `isDisabled` | `boolean` | `false` | 是否禁用触发器 |
| `asChild` | `boolean` | - | 使用 Slot 模式将行为合并到单个子元素 |
| `...PressableProps` | `PressableProps` | - | 支持 React Native `Pressable` 的全部标准属性 |
### Menu.Portal
| prop | type | default | description |
| -------------------------- | ----------------- | ------- | ------------------------------------------------------ |
| `children` | `React.ReactNode` | - | Portal 内容 |
| `className` | `string` | - | Portal 容器额外 class |
| `disableFullWindowOverlay` | `boolean` | `false` | 在 iOS 上使用普通 `View` 替代 `FullWindowOverlay` |
| `unstable_accessibilityContainerViewIsModal` | `boolean` | `false` | 控制 VoiceOver 是否将遮罩窗口视为模态容器。为 `true` 时焦点限制在遮罩内。仅 iOS。不稳定：可能随 `react-native-screens` 更新变化 |
| `hostName` | `string` | - | Portal 宿主元素的可选名称 |
| `forceMount` | `boolean` | - | 无论开闭状态是否强制挂载 Portal |
### Menu.Overlay
| prop | type | default | description |
| ----------------------- | ---------------------- | ------- | ------------------------------------------------------------ |
| `className` | `string` | - | 遮罩额外 class |
| `closeOnPress` | `boolean` | `true` | 点击遮罩时是否关闭菜单 |
| `animation` | `MenuOverlayAnimation` | - | 遮罩动画配置 |
| `isAnimatedStyleActive` | `boolean` | `true` | 是否启用 Reanimated 动画样式 |
| `forceMount` | `boolean` | - | 无论开闭是否强制挂载遮罩 |
| `...PressableProps` | `PressableProps` | - | 支持 React Native `Pressable` 的全部标准属性 |
#### MenuOverlayAnimation
菜单遮罩的动画配置，可为：
- `false` 或 `"disabled"`：关闭所有动画
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| ------------------------ | ----------------------- | ----------------------- | ----------------------------------- |
| `state` | `'disabled' \| boolean` | - | 关闭动画的同时仍允许自定义属性 |
| `opacity.entering.value` | `EntryOrExitLayoutType` | `FadeIn.duration(200)` | 遮罩进入动画 |
| `opacity.exiting.value` | `EntryOrExitLayoutType` | `FadeOut.duration(150)` | 遮罩退出动画 |
### Menu.Content（Popover）
当 `presentation="popover"` 时的属性。
| prop | type | default | description |
| ----------------- | ------------------------------------------------ | --------------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | - | 菜单内容 |
| `presentation` | `'popover'` | - | 呈现方式（须与 Menu 根一致） |
| `placement` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | 相对触发器的弹出方位 |
| `align` | `'start' \| 'center' \| 'end'` | `'center'` | 沿对齐轴相对触发器的对齐方式 |
| `avoidCollisions` | `boolean` | `true` | 是否自动避让屏幕边缘 |
| `offset` | `number` | `9` | 与触发器的间距（像素） |
| `alignOffset` | `number` | `0` | 沿对齐轴的偏移（像素） |
| `width` | `'content-fit' \| 'trigger' \| 'full' \| number` | `'content-fit'` | 内容宽度策略 |
| `className` | `string` | - | 内容容器额外 class |
| `animation` | `MenuContentAnimation` | - | 内容动画配置 |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部标准属性 |
#### MenuContentAnimation
Popover 内容动画配置，可为：
- `false` 或 `"disabled"`：关闭所有动画
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| ---------------- | ----------------------- | ------------------------------- | ------------------------------ |
| `state` | `'disabled' \| boolean` | - | 关闭动画的同时仍允许自定义属性 |
| `entering.value` | `EntryOrExitLayoutType` | Scale + fade entering animation | 自定义进入动画 |
| `exiting.value` | `EntryOrExitLayoutType` | Scale + fade exiting animation | 自定义退出动画 |
### Menu.Content（Bottom Sheet）
当 `presentation="bottom-sheet"` 时的属性。继承 `@gorhom/bottom-sheet` 的 BottomSheet 属性。
| prop | type | default | description |
| --------------------------- | ---------------------------------------- | ------- | ---------------------------------------------------- |
| `children` | `React.ReactNode` | - | 底部抽屉内容 |
| `presentation` | `'bottom-sheet'` | - | 呈现方式（须与 Menu 根一致） |
| `className` | `string` | - | 底部抽屉额外 class |
| `backgroundClassName` | `string` | - | 背景额外 class |
| `handleIndicatorClassName` | `string` | - | 把手指示条额外 class |
| `contentContainerClassName` | `string` | - | 内容容器额外 class |
| `contentContainerProps` | `Omit<BottomSheetViewProps, 'children'>` | - | 内容容器属性 |
| `animation` | `AnimationDisabled` | - | 设为 `false` 或 `"disabled"` 可关闭动画 |
| `...BottomSheetProps` | `Partial<BottomSheetProps>` | - | 支持 `@gorhom/bottom-sheet` 的全部属性 |
### Menu.Close
继承 `CloseButtonProps`。按下后自动关闭菜单。
| prop | type | default | description |
| ---------------- | ---------------------- | ------- | ------------------------------------ |
| `iconProps` | `CloseButtonIconProps` | - | 自定义关闭图标属性 |
| `...ButtonProps` | `ButtonRootProps` | - | 支持 Button 根级全部属性 |
### Menu.Group
| prop | type | default | description |
| --------------------- | ---------------------------------- | -------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | - | 分组内容（`Menu.Item` 等） |
| `selectionMode` | `'none' \| 'single' \| 'multiple'` | `'none'` | 分组内允许的选择类型 |
| `selectedKeys` | `Iterable<MenuKey>` | - | 当前选中键（受控） |
| `defaultSelectedKeys` | `Iterable<MenuKey>` | - | 初始选中键（非受控） |
| `isDisabled` | `boolean` | `false` | 是否禁用整个分组 |
| `disabledKeys` | `Iterable<MenuKey>` | - | 应禁用的项键集合 |
| `shouldCloseOnSelect` | `boolean` | - | 选中项时是否关闭菜单 |
| `className` | `string` | - | 分组容器额外 class |
| `onSelectionChange` | `(keys: Set<MenuKey>) => void` | - | 选中变化时回调 |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部标准属性 |
### Menu.Label
| prop | type | default | description |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | - | 标签文本内容 |
| `className` | `string` | - | 标签额外 class |
| `...TextProps` | `TextProps` | - | 支持 React Native `Text` 的全部标准属性 |
### Menu.Item
| prop | type | default | description |
| ----------------------- | ---------------------------------------------------------------- | ----------- | ------------------------------------------------------------ |
| `children` | `React.ReactNode \| ((props: MenuItemRenderProps) => ReactNode)` | - | 子元素或渲染函数 |
| `id` | `MenuKey` | - | 唯一标识；在 `Menu.Group` 内时必填 |
| `variant` | `'default' \| 'danger'` | `'default'` | 菜单项视觉变体 |
| `isDisabled` | `boolean` | `false` | 是否禁用该项 |
| `isSelected` | `boolean` | - | 独立项时的受控选中状态 |
| `shouldCloseOnSelect` | `boolean` | `true` | 按压该项是否关闭菜单 |
| `className` | `string` | - | 菜单项额外 class |
| `animation` | `MenuItemAnimation` | - | 按压反馈动画配置 |
| `isAnimatedStyleActive` | `boolean` | `true` | 是否启用 Reanimated 动画样式 |
| `onSelectedChange` | `(selected: boolean) => void` | - | 独立项选中状态变化时回调 |
| `...PressableProps` | `PressableProps` | - | 支持 React Native `Pressable` 的全部标准属性 |
#### MenuItemRenderProps
当 `children` 为函数时传入渲染函数的参数。
| prop | type | description |
| ------------ | ----------------------- | --------------------------------------- |
| `isSelected` | `boolean` | 当前项是否选中 |
| `isDisabled` | `boolean` | 是否禁用 |
| `isPressed` | `SharedValue<boolean>` | 是否处于按压中 |
| `variant` | `'default' \| 'danger'` | 项的视觉变体 |
#### MenuItemAnimation
菜单项按压反馈动画配置，可为：
- `false` 或 `"disabled"`：关闭项动画
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| ------------------------------ | ------------------ | -------------------------- | ------------------------------ |
| `scale.value` | `number` | `0.98` | 按压时的缩放值 |
| `scale.timingConfig` | `WithTimingConfig` | `{ duration: 150 }` | 缩放的动画配置 |
| `backgroundColor.value` | `string` | `useThemeColor('default')` | 按压时背景色 |
| `backgroundColor.timingConfig` | `WithTimingConfig` | `{ duration: 150 }` | 背景色过渡时间配置 |
### Menu.ItemTitle
| prop | type | default | description |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | - | 标题文本内容 |
| `className` | `string` | - | 标题额外 class |
| `...TextProps` | `TextProps` | - | 支持 React Native `Text` 的全部标准属性 |
### Menu.ItemDescription
| prop | type | default | description |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | - | 说明文本内容 |
| `className` | `string` | - | 说明额外 class |
| `...TextProps` | `TextProps` | - | 支持 React Native `Text` 的全部标准属性 |
### Menu.ItemIndicator
| prop | type | default | description |
| -------------- | ---------------------------- | ------------- | ------------------------------------------------------ |
| `children` | `React.ReactNode` | - | 自定义指示内容；默认为对勾或圆点 |
| `variant` | `'checkmark' \| 'dot'` | `'checkmark'` | 指示器视觉变体 |
| `iconProps` | `MenuItemIndicatorIconProps` | - | 图标配置（对勾变体） |
| `forceMount` | `boolean` | `true` | 无论是否选中都强制挂载指示器 |
| `className` | `string` | - | 指示器额外 class |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部标准属性 |
#### MenuItemIndicatorIconProps
| prop | type | default | description |
| ------- | -------- | ------- | ---------------------------------------------- |
| `size` | `number` | `16` | 指示图标尺寸（圆点变体为 8） |
| `color` | `string` | `muted` | 指示图标颜色 |
### SubMenu
| prop | type | default | description |
| --------------- | ------------------------- | ------- | -------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 子菜单内容（触发器、内容区等） |
| `isOpen` | `boolean` | - | 受控开闭状态 |
| `isDefaultOpen` | `boolean` | - | 非受控：首次渲染时是否打开 |
| `isDisabled` | `boolean` | `false` | 是否禁用子菜单 |
| `className` | `string` | - | 根容器额外 class |
| `animation` | `SubMenuRootAnimation` | - | 子菜单动画配置 |
| `onOpenChange` | `(open: boolean) => void` | - | 开闭状态变化时回调 |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部标准属性 |
##### SubMenuRootAnimation
SubMenu 根组件动画配置，可为：
- `"disable-all"`：关闭所有动画（含子级）
- `false` 或 `"disabled"`：仅关闭根级动画
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| ------------------------------- | ----------------------- | ------------------------------------------- | -------------------------------------- |
| `state` | `'disabled' \| boolean` | - | 关闭动画的同时仍允许自定义属性 |
| `rootContent.marginHorizontal` | `number` | `-16` | 子菜单打开时水平外边距 |
| `rootContent.marginVertical` | `number` | `-16` | 子菜单打开时垂直外边距 |
| `rootContent.paddingHorizontal` | `number` | `6` | 子菜单打开时水平内边距 |
| `rootContent.paddingTop` | `number` | `12` | 子菜单打开时顶部内边距 |
| `rootContent.springConfig` | `WithSpringConfig` | `{ damping: 100, stiffness: 950, mass: 3 }` | 展开/收起的弹簧配置 |
#### SubMenu.Trigger
| prop | type | default | description |
| ------------------- | ----------------- | ------- | ------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 触发器内容（标题、图标、指示器等） |
| `textValue` | `string` | - | 读屏播报的无障碍文本 |
| `className` | `string` | - | 触发器额外 class |
| `isDisabled` | `boolean` | `false` | 是否禁用 |
| `asChild` | `boolean` | - | 使用 Slot 模式合并到单个子元素 |
| `...PressableProps` | `PressableProps` | - | 支持 React Native `Pressable` 的全部标准属性 |
#### SubMenu.TriggerIndicator
子菜单开闭时旋转的指示图标，默认为向右 V 形（chevron-right）。
| prop | type | default | description |
| ----------------------- | ---------------------------------- | ------- | ------------------------------------------------------------ |
| `children` | `React.ReactNode` | - | 自定义指示内容（替换默认 V 形） |
| `className` | `string` | - | 指示器额外 class |
| `iconProps` | `SubMenuTriggerIndicatorIconProps` | - | 默认 V 形的图标配置 |
| `animation` | `SubMenuTriggerIndicatorAnimation` | - | 指示器旋转动画配置 |
| `isAnimatedStyleActive` | `boolean` | `true` | 是否启用 Reanimated 动画样式 |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部标准属性 |
##### SubMenuTriggerIndicatorIconProps
| prop | type | default | description |
| ------- | -------- | ------- | --------------------------- |
| `size` | `number` | `14` | 指示图标尺寸 |
| `color` | `string` | `muted` | 指示图标颜色 |
##### SubMenuTriggerIndicatorAnimation
触发器指示旋转的动画配置，可为：
- `false` 或 `"disabled"`：关闭所有动画
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| ----------------------- | ----------------------- | -------------------------------------------- | ------------------------------------------------ |
| `state` | `'disabled' \| boolean` | - | 关闭动画的同时仍允许自定义属性 |
| `rotation.value` | `[number, number]` | `[0, 90]` | 旋转角度 [收起, 展开]，单位度 |
| `rotation.springConfig` | `WithSpringConfig` | `{ damping: 140, stiffness: 1000, mass: 4 }` | 旋转弹簧配置 |
#### SubMenu.Content
| prop | type | default | description |
| ------------------- | ----------------- | ------- | ------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 子菜单项（`Menu.Item`、`Menu.Group` 等） |
| `className` | `string` | - | 内容容器额外 class |
| `...PressableProps` | `PressableProps` | - | 支持 React Native `Pressable` 的全部标准属性 |
## Hooks
### useMenu
访问菜单根上下文，须在 `Menu` 内使用。
```tsx
import { useMenu } from 'heroui-native';
const { isOpen, onOpenChange, presentation, isDisabled } = useMenu();
```
#### 返回值
| property | type | description |
| -------------- | ----------------------------- | --------------------------------------- |
| `isOpen` | `boolean` | 菜单是否打开 |
| `onOpenChange` | `(open: boolean) => void` | 修改开闭状态的回调 |
| `presentation` | `'popover' \| 'bottom-sheet'` | 当前呈现模式 |
| `isDisabled` | `boolean \| undefined` | 是否禁用 |
| `nativeID` | `string` | 菜单实例唯一标识 |
### useMenuItem
访问菜单项上下文，须在 `Menu.Item` 内使用。
```tsx
import { useMenuItem } from 'heroui-native';
const { id, isSelected, isDisabled, variant } = useMenuItem();
```
#### 返回值
| property | type | description |
| ------------ | ----------------------- | -------------------------------------- |
| `id` | `MenuKey \| undefined` | 项标识 |
| `isSelected` | `boolean` | 是否选中 |
| `isDisabled` | `boolean` | 是否禁用 |
| `variant` | `'default' \| 'danger'` | 项的视觉变体 |
### useMenuAnimation
访问菜单动画上下文，须在 `Menu` 内使用。
```tsx
import { useMenuAnimation } from 'heroui-native';
const { progress, isDragging } = useMenuAnimation();
```
#### 返回值
| property | type | description |
| ------------ | ---------------------- | --------------------------------------------------------- |
| `progress` | `SharedValue<number>` | 动画进度（0=空闲，1=打开，2=关闭） |
| `isDragging` | `SharedValue<boolean>` | Bottom Sheet 是否正在被拖拽 |
### useSubMenu
访问子菜单上下文，须在 `SubMenu` 内使用。
```tsx
import { useSubMenu } from 'heroui-native';
const { isOpen, onOpenChange, isDisabled } = useSubMenu();
```
#### 返回值
| property | type | description |
| -------------- | ------------------------- | ------------------------------------------- |
| `isOpen` | `boolean` | 子菜单是否打开 |
| `onOpenChange` | `(open: boolean) => void` | 修改开闭状态的回调 |
| `isDisabled` | `boolean` | 是否禁用 |
| `nativeID` | `string` | 子菜单实例唯一标识 |
## 特别说明
### 元素检查器（iOS）
Menu 在 iOS 上使用 `FullWindowOverlay`。开发时若需启用 React Native 元素检查器，请在 `Menu.Portal` 上设置 `disableFullWindowOverlay={true}`。代价是菜单将无法叠在原生模态之上。
### 原生模态（iOS）
当 `Menu` 位于以原生模态形式呈现的页面内时（`presentation: 'modal' | 'formSheet' | 'pageSheet'`），菜单内容可能会向上偏移渲染。在新架构（Fabric）中，`react-native-screens` 将 `RNSModalScreen` 标记为 Fabric 根节点，因此触发器的坐标是相对于模态原点上报的，而 `FullWindowOverlay`（菜单挂载点）锚定在 iOS 应用窗口上。可通过将 `safeAreaInsets.top` 加到 `offset` 来补偿：
```tsx
import { useSafeAreaInsets } from 'react-native-safe-area-context';
const insets = useSafeAreaInsets();
<Menu.Content presentation="popover" offset={insets.top}>
...
</Menu.Content>;
```
apps/docs/content/docs/cn/native/components/(collections)/tag-group.mdx
+414
View File
@@ -0,0 +1,414 @@
---
title: TagGroup 标签组
description: 用于展示与管理可选标签的复合组件，支持可选移除。
links:
source_native: tag-group/tag-group.tsx
styles_native: tag-group/tag-group.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/tag-group-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/tag-group-docs-dark.mp4"
/>
## 导入
```tsx
import { TagGroup } from 'heroui-native';
```
## 结构
```tsx
<TagGroup>
<TagGroup.List>
<TagGroup.Item id="tag-1">
<TagGroup.ItemLabel>...</TagGroup.ItemLabel>
<TagGroup.ItemRemoveButton />
</TagGroup.Item>
</TagGroup.List>
</TagGroup>
```
- **TagGroup**：主容器，管理标签选中状态、禁用键与移除能力，并向子组件提供尺寸与变体上下文。
- **TagGroup.List**：渲染标签列表的容器，可渲染空状态。
- **TagGroup.Item**：组内单个标签。支持字符串子节点（自动包在 `TagGroup.ItemLabel`）、渲染函数子节点或自定义布局。
- **TagGroup.ItemLabel**：标签文字。提供字符串子节点时会自动渲染，也可显式使用。
- **TagGroup.ItemRemoveButton**：移除按钮；需要移除能力时需显式放置。仅当 `TagGroup` 传入 `onRemove` 时生效。
## 用法
### 基础用法
展示一个简单的可选标签组。
```tsx
<TagGroup selectionMode="single">
<TagGroup.List>
<TagGroup.Item id="news">新闻</TagGroup.Item>
<TagGroup.Item id="travel">旅行</TagGroup.Item>
<TagGroup.Item id="gaming">游戏</TagGroup.Item>
</TagGroup.List>
</TagGroup>
```
### 单选模式
同一时间只能选中一个标签。
```tsx
<TagGroup selectionMode="single" defaultSelectedKeys={['news']}>
<TagGroup.List>
<TagGroup.Item id="news">新闻</TagGroup.Item>
<TagGroup.Item id="travel">旅行</TagGroup.Item>
<TagGroup.Item id="gaming">游戏</TagGroup.Item>
</TagGroup.List>
</TagGroup>
```
### 多选模式
允许多个标签同时选中。
```tsx
<TagGroup selectionMode="multiple" defaultSelectedKeys={['news', 'travel']}>
<TagGroup.List>
<TagGroup.Item id="news">新闻</TagGroup.Item>
<TagGroup.Item id="travel">旅行</TagGroup.Item>
<TagGroup.Item id="gaming">游戏</TagGroup.Item>
</TagGroup.List>
</TagGroup>
```
### 受控选中
通过 `selectedKeys` 与 `onSelectionChange` 控制选中状态。
```tsx
const [selected, setSelected] = useState(new Set(['news']));
<TagGroup
selectionMode="single"
selectedKeys={selected}
onSelectionChange={setSelected}
>
<TagGroup.List>
<TagGroup.Item id="news">新闻</TagGroup.Item>
<TagGroup.Item id="travel">旅行</TagGroup.Item>
<TagGroup.Item id="gaming">游戏</TagGroup.Item>
</TagGroup.List>
</TagGroup>;
```
### 变体
为标签应用不同视觉变体。
```tsx
<TagGroup selectionMode="single" variant="default">
<TagGroup.List>
<TagGroup.Item id="news">新闻</TagGroup.Item>
<TagGroup.Item id="travel">旅行</TagGroup.Item>
</TagGroup.List>
</TagGroup>
<TagGroup selectionMode="single" variant="surface">
<TagGroup.List>
<TagGroup.Item id="news">新闻</TagGroup.Item>
<TagGroup.Item id="travel">旅行</TagGroup.Item>
</TagGroup.List>
</TagGroup>
```
### 尺寸
控制组内所有标签的尺寸。
```tsx
<TagGroup selectionMode="single" size="sm">
<TagGroup.List>
<TagGroup.Item id="news">新闻</TagGroup.Item>
</TagGroup.List>
</TagGroup>
<TagGroup selectionMode="single" size="md">
<TagGroup.List>
<TagGroup.Item id="news">新闻</TagGroup.Item>
</TagGroup.List>
</TagGroup>
<TagGroup selectionMode="single" size="lg">
<TagGroup.List>
<TagGroup.Item id="news">新闻</TagGroup.Item>
</TagGroup.List>
</TagGroup>
```
### 带移除按钮
提供 `onRemove`，并在每个条目中放置 `TagGroup.ItemRemoveButton` 以显示移除按钮。
```tsx
const [tags, setTags] = useState([
{ id: 'news', name: '新闻' },
{ id: 'travel', name: '旅行' },
]);
const onRemove = (keys) => {
setTags((prev) => prev.filter((tag) => !keys.has(tag.id)));
};
<TagGroup selectionMode="single" onRemove={onRemove}>
<TagGroup.List>
{tags.map((tag) => (
<TagGroup.Item key={tag.id} id={tag.id}>
<TagGroup.ItemLabel>{tag.name}</TagGroup.ItemLabel>
<TagGroup.ItemRemoveButton />
</TagGroup.Item>
))}
</TagGroup.List>
</TagGroup>;
```
### 渲染函数子节点
使用渲染函数访问 `isSelected`、`isDisabled` 以自定义布局。
```tsx
<TagGroup selectionMode="single">
<TagGroup.List>
<TagGroup.Item id="news">
{({ isSelected }) => (
<>
<SquareArticleIcon
size={16}
colorClassName={
isSelected
? 'accent-accent-soft-foreground'
: 'accent-field-foreground'
}
/>
<TagGroup.ItemLabel>新闻</TagGroup.ItemLabel>
</>
)}
</TagGroup.Item>
</TagGroup.List>
</TagGroup>
```
### 空状态
列表无标签时渲染自定义内容。
```tsx
<TagGroup onRemove={onRemove}>
<TagGroup.List
renderEmptyState={() => (
<Text className="text-sm text-muted">暂无分类</Text>
)}
>
{tags.map((tag) => (
<TagGroup.Item key={tag.id} id={tag.id}>
<TagGroup.ItemLabel>{tag.name}</TagGroup.ItemLabel>
<TagGroup.ItemRemoveButton />
</TagGroup.Item>
))}
</TagGroup.List>
</TagGroup>
```
### 禁用标签
禁用单个标签或整个组。
```tsx
<TagGroup selectionMode="single" disabledKeys={new Set(['travel'])}>
<TagGroup.List>
<TagGroup.Item id="news">新闻</TagGroup.Item>
<TagGroup.Item id="travel">旅行</TagGroup.Item>
<TagGroup.Item id="gaming" isDisabled>
游戏
</TagGroup.Item>
</TagGroup.List>
</TagGroup>
```
## 示例
```tsx
import { TagGroup, Label, Description, FieldError } from 'heroui-native';
import { useState, useMemo } from 'react';
import { View } from 'react-native';
export default function TagGroupExample() {
const [selected, setSelected] = useState(new Set());
const isInvalid = useMemo(
() => Array.from(selected).length === 0,
[selected]
);
return (
<View className="gap-4">
<TagGroup
selectedKeys={selected}
selectionMode="multiple"
onSelectionChange={setSelected}
isInvalid={isInvalid}
>
<Label isInvalid={false}>设施</Label>
<TagGroup.List>
<TagGroup.Item id="laundry">洗衣</TagGroup.Item>
<TagGroup.Item id="fitness">健身房</TagGroup.Item>
<TagGroup.Item id="parking">停车</TagGroup.Item>
<TagGroup.Item id="pool">泳池</TagGroup.Item>
<TagGroup.Item id="breakfast">早餐</TagGroup.Item>
</TagGroup.List>
<Description hideOnInvalid>
{`已选：${Array.from(selected).join('、')}`}
</Description>
<FieldError>请至少选择一个分类</FieldError>
</TagGroup>
</View>
);
}
```
更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/tag-group.tsx>)。
## API 参考
### TagGroup
| prop | type | default | description |
| --------------------- | ---------------------------------- | ----------- | ---------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 渲染在标签组内的子节点 |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 组内所有标签的尺寸 |
| `variant` | `'default' \| 'surface'` | `'default'` | 组内所有标签的视觉变体 |
| `selectionMode` | `'none' \| 'single' \| 'multiple'` | `'none'` | 允许的选中类型 |
| `selectedKeys` | `Iterable<TagKey>` | - | 当前选中键（受控） |
| `defaultSelectedKeys` | `Iterable<TagKey>` | - | 初始选中键（非受控） |
| `disabledKeys` | `Iterable<TagKey>` | - | 应被禁用的标签键 |
| `isDisabled` | `boolean` | `false` | 是否禁用整个标签组 |
| `isInvalid` | `boolean` | `false` | 是否处于非法状态 |
| `isRequired` | `boolean` | `false` | 是否必填 |
| `className` | `string` | - | 标签组容器的额外 class |
| `style` | `StyleProp<ViewStyle>` | - | 标签组容器的额外样式 |
| `animation` | `"disable-all" \| undefined` | - | 设为 `"disable-all"` 可禁用全部动画（含子级） |
| `onSelectionChange` | `(keys: Set<TagKey>) => void` | - | 选中变化时调用 |
| `onRemove` | `(keys: Set<TagKey>) => void` | - | 移除标签时调用 |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部属性 |
#### TagKey
`string | number` — 在 `TagGroup` 内标识标签的键类型。
#### Animation
使用 `animation="disable-all"` 可禁用全部动画（含子级）。省略或使用 `undefined` 为默认动画。
### TagGroup.List
| prop | type | default | description |
| ------------------ | ----------------------- | ------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | - | 列表内的子节点 |
| `className` | `string` | - | 列表容器的额外 class |
| `style` | `StyleProp<ViewStyle>` | - | 列表容器的额外样式 |
| `renderEmptyState` | `() => React.ReactNode` | - | 无标签时调用的渲染函数 |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部属性 |
### TagGroup.Item
| prop | type | default | description |
| ------------------- | ----------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------- |
| `children` | `React.ReactNode \| ((renderProps: TagRenderProps) => React.ReactNode)` | - | 标签内容：字符串、元素，或接收 `TagRenderProps` 的渲染函数 |
| `id` | `TagKey` | - | 该标签的唯一标识 |
| `isDisabled` | `boolean` | - | 是否禁用该标签 |
| `className` | `string` | - | 标签的额外 class |
| `style` | `StyleProp<ViewStyle>` | - | 标签的额外样式 |
| `...PressableProps` | `PressableProps` | - | 支持 React Native `Pressable` 的全部属性 |
#### TagRenderProps
| prop | type | description |
| ------------ | --------- | --------------------------------------------------------------------------- |
| `isSelected` | `boolean` | 当前是否选中 |
| `isDisabled` | `boolean` | 是否禁用（根级、`disabledKeys` 与条目属性合并后的结果） |
### TagGroup.ItemLabel
| prop | type | default | description |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | - | 要渲染的文字内容 |
| `className` | `string` | - | 标签文字的额外 class |
| `...TextProps` | `TextProps` | - | 支持 React Native `Text` 的全部属性 |
### TagGroup.ItemRemoveButton
| prop | type | default | description |
| ------------------- | -------------------------- | ------- | ---------------------------------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 自定义图标或内容；省略时默认为关闭图标 |
| `className` | `string` | - | 移除按钮的额外 class |
| `iconProps` | `TagRemoveButtonIconProps` | - | 自定义默认关闭图标的属性；仅在没有 `children` 时生效 |
| `hitSlop` | `number` | `8` | 扩大可点击区域 |
| `...PressableProps` | `PressableProps` | - | 支持 React Native `Pressable` 的全部属性 |
#### TagRemoveButtonIconProps
| prop | type | default | description |
| ------- | -------- | ------- | ----------- |
| `size` | `number` | `12` | 图标尺寸 |
| `color` | `string` | - | 图标颜色 |
## Hooks
### useTagGroup
访问标签组根上下文，必须在 `TagGroup` 内使用。
```tsx
import { useTagGroup } from 'heroui-native';
const {
selectedKeys,
disabledKeys,
selectionMode,
onSelectionChange,
onRemove,
isDisabled,
isInvalid,
isRequired,
} = useTagGroup();
```
#### 返回值
| property | type | description |
| ------------------- | -------------------------------------------- | ------------------------------ |
| `selectionMode` | `'none' \| 'single' \| 'multiple'` | 允许的选中类型 |
| `selectedKeys` | `Set<TagKey>` | 当前选中的标签键 |
| `disabledKeys` | `Set<TagKey>` | 被禁用的标签键 |
| `onSelectionChange` | `(keys: Set<TagKey>) => void` | 选中变化回调 |
| `onRemove` | `((keys: Set<TagKey>) => void) \| undefined` | 移除标签回调 |
| `isDisabled` | `boolean` | 是否禁用整个标签组 |
| `isInvalid` | `boolean` | 是否处于非法状态 |
| `isRequired` | `boolean` | 是否必填 |
### useTagGroupItem
访问单个标签上下文，必须在 `TagGroup.Item` 内使用。
```tsx
import { useTagGroupItem } from 'heroui-native';
const { id, isSelected, isDisabled, allowsRemoving } = useTagGroupItem();
```
#### 返回值
| property | type | description |
| ---------------- | --------- | --------------------------------------------------------------------------- |
| `id` | `TagKey` | 该标签的唯一标识 |
| `isSelected` | `boolean` | 当前是否选中 |
| `isDisabled` | `boolean` | 是否禁用 |
| `allowsRemoving` | `boolean` | 是否允许移除（当 `TagGroup` 提供 `onRemove` 时为 true） |
apps/docs/content/docs/cn/native/components/(controls)/slider.mdx
+358
View File
@@ -0,0 +1,358 @@
---
title: Slider 滑块
description: 在有限区间内通过拖拽选择单个值或区间的输入控件。
links:
source_native: slider/slider.tsx
styles_native: slider/slider.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/slider-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/slider-docs-dark.mp4"
/>
## 导入
```tsx
import { Slider } from 'heroui-native';
```
## 结构
```tsx
<Slider>
<Slider.Output />
<Slider.Track>
<Slider.Fill />
<Slider.Thumb />
</Slider.Track>
</Slider>
```
- **Slider**：主容器，管理滑块数值、方向，并为所有子组件提供上下文。支持单值与区间模式。
- **Slider.Output**：可选，显示当前值；支持渲染函数以自定义格式；默认显示格式化后的数值标签。
- **Slider.Track**：为 Fill 与 Thumb 提供尺寸的容器；上报布局尺寸用于位置计算；支持点击定位与渲染函数子节点（例如区间滑块的多拇指）。
- **Slider.Fill**：沿轨道交叉轴铺满的填充条；仅计算主轴位置与尺寸。
- **Slider.Thumb**：基于 react-native-gesture-handler 的可拖拽拇指；由 Track 布局在交叉轴居中；通过 react-native-reanimated 在按压时缩放。每个拇指具备 `role="slider"` 与完整 `accessibilityValue`。
## 用法
### 基础用法
Slider 通过复合部件组成可拖拽的数值输入。
```tsx
<Slider defaultValue={30}>
<Slider.Output />
<Slider.Track>
<Slider.Fill />
<Slider.Thumb />
</Slider.Track>
</Slider>
```
### 标签与输出
在数值输出旁显示标签。
```tsx
<Slider defaultValue={50}>
<View className="flex-row items-center justify-between">
<Label>Volume</Label>
<Slider.Output />
</View>
<Slider.Track>
<Slider.Fill />
<Slider.Thumb />
</Slider.Track>
</Slider>
```
### 纵向
将 `orientation` 设为 `"vertical"` 以纵向渲染。
```tsx
<View className="h-48">
<Slider defaultValue={50} orientation="vertical">
<Slider.Track>
<Slider.Fill />
<Slider.Thumb />
</Slider.Track>
</Slider>
</View>
```
### 区间滑块
将 `value`/`defaultValue` 设为数组，并在 `Slider.Track` 上使用渲染函数以渲染多个拇指。
```tsx
<Slider
defaultValue={[200, 800]}
minValue={0}
maxValue={1000}
step={10}
formatOptions={{ style: 'currency', currency: 'USD' }}
>
<View className="flex-row items-center justify-between">
<Label>Price range</Label>
<Slider.Output />
</View>
<Slider.Track>
{({ state }) => (
<>
<Slider.Fill />
{state.values.map((_, i) => (
<Slider.Thumb key={i} index={i} />
))}
</>
)}
</Slider.Track>
</Slider>
```
### 受控值
使用 `value` 与 `onChange` 进入受控模式。`onChangeEnd` 在拖拽结束或点击定位完成后触发。
```tsx
const [volume, setVolume] = useState(50);
<Slider value={volume} onChange={setVolume} onChangeEnd={(v) => save(v)}>
<Slider.Output />
<Slider.Track>
<Slider.Fill />
<Slider.Thumb />
</Slider.Track>
</Slider>;
```
### 自定义样式
在拇指等子组件上使用 `className`、`classNames` 或 `styles` 自定义样式。
```tsx
<Slider defaultValue={65}>
<Slider.Track className="h-3 rounded-full bg-success/10">
<Slider.Fill className="rounded-full bg-success" />
<Slider.Thumb
classNames={{
thumbContainer: 'size-6 rounded-full bg-success',
thumbKnob: 'bg-success-foreground rounded-full',
}}
animation={{
scale: { value: [1, 0.7] },
}}
/>
</Slider.Track>
</Slider>
```
### 禁用
禁用整个滑块以禁止交互。
```tsx
<Slider defaultValue={40} isDisabled>
<Slider.Track>
<Slider.Fill />
<Slider.Thumb />
</Slider.Track>
</Slider>
```
## 示例
```tsx
import { Label, Slider } from 'heroui-native';
import { useState } from 'react';
import { View, Text } from 'react-native';
export default function SliderExample() {
const [price, setPrice] = useState<number[]>([200, 800]);
return (
<View className="px-8 gap-8">
<Slider defaultValue={30}>
<View className="flex-row items-center justify-between">
<Label>Volume</Label>
<Slider.Output />
</View>
<Slider.Track>
<Slider.Fill />
<Slider.Thumb />
</Slider.Track>
</Slider>
<Slider
value={price}
onChange={setPrice}
minValue={0}
maxValue={1000}
step={10}
formatOptions={{ style: 'currency', currency: 'USD' }}
>
<View className="flex-row items-center justify-between">
<Label>Price range</Label>
<Slider.Output />
</View>
<Slider.Track>
{({ state }) => (
<>
<Slider.Fill />
{state.values.map((_, i) => (
<Slider.Thumb key={i} index={i} />
))}
</>
)}
</Slider.Track>
</Slider>
</View>
);
}
```
更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/slider.tsx>)。
## API 参考
### Slider
| prop | type | default | description |
| --------------- | ------------------------------------- | -------------- | --------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 滑块内部子元素 |
| `value` | `number \| number[]` | - | 当前值（受控） |
| `defaultValue` | `number \| number[]` | `0` | 默认值（非受控） |
| `minValue` | `number` | `0` | 最小值 |
| `maxValue` | `number` | `100` | 最大值 |
| `step` | `number` | `1` | 步进 |
| `formatOptions` | `Intl.NumberFormatOptions` | - | 数值标签的 `Intl` 格式化选项 |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | 方向 |
| `isDisabled` | `boolean` | `false` | 是否禁用 |
| `className` | `string` | - | 额外 class |
| `animation` | `AnimationRootDisableAll` | - | 根级动画配置 |
| `onChange` | `(value: number \| number[]) => void` | - | 交互过程中数值变化时触发 |
| `onChangeEnd` | `(value: number \| number[]) => void` | - | 交互结束（拖放结束或点击定位）时触发 |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部标准属性 |
#### AnimationRootDisableAll
滑块根组件动画配置，可为：
- `"disable-all"`：关闭所有动画（含子级）
- `undefined`：使用默认动画
### Slider.Output
| prop | type | default | description |
| -------------- | -------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------- |
| `children` | `React.ReactNode \| ((props: SliderRenderProps) => React.ReactNode)` | - | 自定义内容或接收滑块状态的渲染函数；默认显示格式化数值标签 |
| `className` | `string` | - | 额外 class |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部标准属性 |
#### SliderRenderProps
| prop | type | description |
| ------------- | ------------------- | ------------------------------ |
| `state` | `SliderState` | 当前滑块状态 |
| `orientation` | `SliderOrientation` | 滑块方向 |
| `isDisabled` | `boolean` | 是否禁用 |
#### SliderState
| prop | type | description |
| -------------------- | --------------------------- | ---------------------------------------------- |
| `values` | `number[]` | 按拇指索引的当前数值数组 |
| `getThumbValueLabel` | `(index: number) => string` | 返回指定拇指的格式化字符串标签 |
### Slider.Track
| prop | type | default | description |
| -------------- | -------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------- |
| `children` | `React.ReactNode \| ((props: SliderRenderProps) => React.ReactNode)` | - | 子内容或接收滑块状态的渲染函数，用于动态渲染多拇指等 |
| `className` | `string` | - | 额外 class |
| `hitSlop` | `number` | `8` | 轨道周围扩展点击区域（像素） |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部标准属性 |
### Slider.Fill
| prop | type | default | description |
| -------------- | ----------- | ------- | -------------------------------------------------- |
| `className` | `string` | - | 额外 class |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部标准属性 |
### Slider.Thumb
| prop | type | default | description |
| -------------- | ---------------------------------------- | ------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | - | 自定义拇指内容；默认可动画圆钮 |
| `index` | `number` | `0` | 该拇指在滑块中的索引 |
| `isDisabled` | `boolean` | - | 是否仅禁用该拇指 |
| `className` | `string` | - | 拇指容器额外 class |
| `classNames` | `ElementSlots<ThumbSlots>` | - | 各拇指插槽的额外 class |
| `styles` | `Partial<Record<ThumbSlots, ViewStyle>>` | - | 各拇指插槽的行内样式 |
| `hitSlop` | `number` | `12` | 拇指周围扩展点击区域（像素） |
| `animation` | `SliderThumbAnimation` | - | 拇指圆钮动画配置 |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部标准属性 |
#### ElementSlots\<ThumbSlots\>
| prop | type | description |
| ---------------- | -------- | ------------------------------- |
| `thumbContainer` | `string` | 外层拇指容器自定义 class |
| `thumbKnob` | `string` | 内层圆钮自定义 class |
#### styles
| prop | type | description |
| ---------------- | ----------- | --------------------- |
| `thumbContainer` | `ViewStyle` | 外层拇指容器样式 |
| `thumbKnob` | `ViewStyle` | 内层圆钮样式 |
#### SliderThumbAnimation
拇指缩放动画配置，可为：
- `false` 或 `"disabled"`：关闭拇指动画
- `undefined`：使用默认动画
- `object`：自定义缩放动画
| prop | type | default | description |
| -------------------- | ------------------ | -------------------------------------------- | ------------------------------- |
| `scale.value` | `[number, number]` | `[1, 0.9]` | 缩放值 [空闲, 拖拽中] |
| `scale.springConfig` | `WithSpringConfig` | `{ damping: 15, stiffness: 200, mass: 0.5 }` | 缩放弹簧配置 |
## Hooks
### useSlider
访问滑块上下文，须在 `Slider` 内使用。
```tsx
import { useSlider } from 'heroui-native';
const { values, orientation, isDisabled, getThumbValueLabel } = useSlider();
```
#### 返回值
| property | type | description |
| -------------------- | -------------------------------------------- | -------------------------------------------------------------- |
| `values` | `number[]` | 当前各拇指的数值 |
| `minValue` | `number` | 最小值 |
| `maxValue` | `number` | 最大值 |
| `step` | `number` | 步进 |
| `orientation` | `'horizontal' \| 'vertical'` | 当前方向 |
| `isDisabled` | `boolean` | 是否禁用 |
| `formatOptions` | `Intl.NumberFormatOptions \| undefined` | 标签数字格式化选项 |
| `getThumbPercent` | `(index: number) => number` | 返回指定拇指位置百分比（0–1） |
| `getThumbValueLabel` | `(index: number) => string` | 返回指定拇指的格式化标签 |
| `getThumbMinValue` | `(index: number) => number` | 返回指定拇指允许的最小值 |
| `getThumbMaxValue` | `(index: number) => number` | 返回指定拇指允许的最大值 |
| `updateValue` | `(index: number, newValue: number) => void` | 按索引更新拇指数值 |
| `isThumbDragging` | `(index: number) => boolean` | 指定拇指是否正在拖拽 |
| `setThumbDragging` | `(index: number, dragging: boolean) => void` | 设置拇指拖拽状态 |
| `trackSize` | `number` | 轨道布局宽度（横向）或高度（纵向），单位像素 |
| `thumbSize` | `number` | 已测量的拇指尺寸（主轴方向），单位像素 |
apps/docs/content/docs/cn/native/components/(controls)/switch.mdx
+344
View File
@@ -0,0 +1,344 @@
---
title: Switch 开关
description: 在开与关两种状态之间切换的拨动控件。
links:
source_native: switch/switch.tsx
styles_native: switch/switch.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/switch-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/switch-docs-dark.mp4"
/>
## 导入
```tsx
import { Switch } from 'heroui-native';
```
## 结构
```tsx
<Switch>
<Switch.Thumb>...</Switch.Thumb>
<Switch.StartContent>...</Switch.StartContent>
<Switch.EndContent>...</Switch.EndContent>
</Switch>
```
- **Switch**：主容器，处理开关状态与用户交互。未提供子节点时渲染默认拇指；根据选中状态对缩放（按压）与背景色做动画；整块可点以切换。
- **Switch.Thumb**：可选滑动拇指，在位置间移动，弹簧过渡。可放自定义内容（图标等）或通过样式与动画定制。
- **Switch.StartContent**：可选，显示在开关左侧；常用于关态时的图标或文字；在容器内绝对定位。
- **Switch.EndContent**：可选，显示在开关右侧；常用于开态时的图标或文字；在容器内绝对定位。
## 用法
### 基础用法
未提供子节点时，Switch 使用默认拇指渲染。
```tsx
<Switch isSelected={isSelected} onSelectedChange={setIsSelected} />
```
### 自定义拇指
通过 Thumb 子组件替换默认拇指。
```tsx
<Switch isSelected={isSelected} onSelectedChange={setIsSelected}>
<Switch.Thumb>...</Switch.Thumb>
</Switch>
```
### 首尾内容
在开关两侧添加图标或文字。
```tsx
<Switch isSelected={isSelected} onSelectedChange={setIsSelected}>
<Switch.Thumb />
<Switch.StartContent>...</Switch.StartContent>
<Switch.EndContent>...</Switch.EndContent>
</Switch>
```
### 渲染函数
根据开关状态用渲染函数动态渲染内容。
```tsx
<Switch isSelected={isSelected} onSelectedChange={setIsSelected}>
{({ isSelected, isDisabled }) => (
<>
<Switch.Thumb>
{({ isSelected }) => (isSelected ? <CheckIcon /> : <XIcon />)}
</Switch.Thumb>
</>
)}
</Switch>
```
### 自定义动画
为开关根与拇指自定义动画。
```tsx
<Switch
animation={{
scale: {
value: [1, 0.9],
timingConfig: { duration: 200 },
},
backgroundColor: {
value: ['#172554', '#eab308'],
},
}}
>
<Switch.Thumb
animation={{
left: {
value: 4,
springConfig: {
damping: 30,
stiffness: 300,
mass: 1,
},
},
backgroundColor: {
value: ['#dbeafe', '#854d0e'],
},
}}
/>
</Switch>
```
### 关闭动画
可整体关闭动画，或仅关闭部分组件的动画。
```tsx
{
/* 关闭所有动画（含子级） */
}
<Switch animation="disable-all">
<Switch.Thumb />
</Switch>;
{
/* 仅关闭根动画，拇指仍可动画 */
}
<Switch>
<Switch.Thumb animation={false} />
</Switch>;
```
## 示例
```tsx
import { Switch } from 'heroui-native';
import { Ionicons } from '@expo/vector-icons';
import React from 'react';
import { View } from 'react-native';
import Animated, { ZoomIn } from 'react-native-reanimated';
export default function SwitchExample() {
const [darkMode, setDarkMode] = React.useState(false);
return (
<View className="flex-row gap-4">
<Switch
isSelected={darkMode}
onSelectedChange={setDarkMode}
className="w-[56px] h-[32px]"
animation={{
backgroundColor: {
value: ['#172554', '#eab308'],
},
}}
>
<Switch.Thumb
className="size-[22px]"
animation={{
left: {
value: 4,
springConfig: {
damping: 30,
stiffness: 300,
mass: 1,
},
},
}}
/>
<Switch.StartContent className="left-2">
{darkMode && (
<Animated.View key="sun" entering={ZoomIn.springify()}>
<Ionicons name="sunny" size={16} color="#854d0e" />
</Animated.View>
)}
</Switch.StartContent>
<Switch.EndContent className="right-2">
{!darkMode && (
<Animated.View key="moon" entering={ZoomIn.springify()}>
<Ionicons name="moon" size={16} color="#dbeafe" />
</Animated.View>
)}
</Switch.EndContent>
</Switch>
</View>
);
}
```
更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/switch.tsx)。
## API 参考
### Switch
| prop | type | default | description |
| --------------------------- | -------------------------------------------------------------------- | ----------- | ------------------------------------------------------------ |
| `children` | `React.ReactNode \| ((props: SwitchRenderProps) => React.ReactNode)` | `undefined` | 开关内部内容或渲染函数 |
| `isSelected` | `boolean` | `undefined` | 是否选中 |
| `isDisabled` | `boolean` | `false` | 是否禁用、不可交互 |
| `className` | `string` | `undefined` | 根节点自定义 class |
| `animation` | `SwitchRootAnimation` | - | 动画配置 |
| `isAnimatedStyleActive` | `boolean` | `true` | 是否启用 Reanimated 动画样式 |
| `onSelectedChange` | `(isSelected: boolean) => void` | - | 选中状态变化时回调 |
| `...AnimatedPressableProps` | `AnimatedProps<PressableProps>` | - | 支持 Reanimated Pressable 的全部属性 |
#### SwitchRenderProps
| prop | type | description |
| ------------ | --------- | ------------------------------ |
| `isSelected` | `boolean` | 是否选中 |
| `isDisabled` | `boolean` | 是否禁用 |
#### SwitchRootAnimation
Switch 根组件动画配置，可为：
- `false` 或 `"disabled"`：仅关闭根动画
- `"disable-all"`：关闭所有动画（含子级）
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| ------------------------------ | ---------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------- |
| `state` | `'disabled' \| 'disable-all' \| boolean` | - | 关闭动画的同时仍允许自定义属性 |
| `scale.value` | `[number, number]` | `[1, 0.96]` | 缩放值 [未按压, 按压] |
| `scale.timingConfig` | `WithTimingConfig` | `{ duration: 150 }` | 动画时间配置 |
| `backgroundColor.value` | `[string, string]` | 使用主题色 | 背景色 [未选中, 选中] |
| `backgroundColor.timingConfig` | `WithTimingConfig` | `{ duration: 175, easing: Easing.bezier(0.25, 0.1, 0.25, 1) }` | 背景色过渡时间配置 |
### Switch.Thumb
| prop | type | default | description |
| ----------------------- | -------------------------------------------------------------------- | ----------- | ------------------------------------------------------------ |
| `children` | `React.ReactNode \| ((props: SwitchRenderProps) => React.ReactNode)` | `undefined` | 拇指内内容或渲染函数 |
| `className` | `string` | `undefined` | 拇指元素自定义 class |
| `animation` | `SwitchThumbAnimation` | - | 动画配置 |
| `isAnimatedStyleActive` | `boolean` | `true` | 是否启用 Reanimated 动画样式 |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部标准属性 |
#### SwitchThumbAnimation
`Switch.Thumb` 动画配置，可为：
- `false` 或 `"disabled"`：关闭全部动画
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| ------------------------------ | ----------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `state` | `'disabled' \| boolean` | - | 关闭动画的同时仍允许自定义属性 |
| `left.value` | `number` | `2` | 距边缘偏移（未选中偏左，选中偏右） |
| `left.springConfig` | `WithSpringConfig` | `{ damping: 120, stiffness: 1600, mass: 2 }` | 拇指位置弹簧配置 |
| `backgroundColor.value` | `[string, string]` | `['white', theme accent-foreground color]` | 背景色 [未选中, 选中] |
| `backgroundColor.timingConfig` | `WithTimingConfig` | `{ duration: 175, easing: Easing.bezier(0.25, 0.1, 0.25, 1) }` | 背景色过渡时间配置 |
### Switch.StartContent
| prop | type | default | description |
| -------------- | ----------------- | ----------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | `undefined` | 左侧区域内容 |
| `className` | `string` | `undefined` | 内容区域自定义 class |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部标准属性 |
### Switch.EndContent
| prop | type | default | description |
| -------------- | ----------------- | ----------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | `undefined` | 右侧区域内容 |
| `className` | `string` | `undefined` | 内容区域自定义 class |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部标准属性 |
## Hooks
### useSwitch
用于访问 Switch 上下文，便于在子组件中读取开关状态或封装自定义结构。
**返回值：**
| Property | Type | Description |
| ------------ | --------- | ------------------------------ |
| `isSelected` | `boolean` | 是否选中 |
| `isDisabled` | `boolean` | 是否禁用 |
**示例：**
```tsx
import { useSwitch } from 'heroui-native';
function CustomSwitchContent() {
const { isSelected, isDisabled } = useSwitch();
return (
<View>
<Text>Status: {isSelected ? 'On' : 'Off'}</Text>
{isDisabled && <Text>Disabled</Text>}
</View>
);
}
// 用法
<Switch>
<CustomSwitchContent />
<Switch.Thumb />
</Switch>;
```
## 特别说明
### 边框样式
若需为开关根节点加边框，请使用 `outline` 相关样式而非 `border`，避免影响拇指位置的内部宽度计算：
```tsx
<Switch className="outline outline-accent">
<Switch.Thumb />
</Switch>
```
使用 `outline` 可在不改变内部宽度计算的前提下显示边框，确保拇指动画正确。
### 与 ControlField 组合
Switch 可与 ControlField 组合以共享按压态、扩大点击区域：
```tsx
import { Description, ControlField, Label } from 'heroui-native';
<ControlField isSelected={isSelected} onSelectedChange={setIsSelected}>
<View className="flex-1">
<Label>Enable notifications</Label>
<Description>Receive push notifications</Description>
</View>
<ControlField.Indicator />
</ControlField>
```
包在 ControlField 内时，整个容器上的按压都会驱动开关，触控目标更大、体验更好。
apps/docs/content/docs/cn/native/components/(data-display)/chip.mdx
+200
View File
@@ -0,0 +1,200 @@
---
title: Chip 标签
description: 以胶囊形态展示的小型元素。
links:
source_native: chip/chip.tsx
styles_native: chip/chip.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/chip-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/chip-docs-dark.mp4"
/>
## 导入
```tsx
import { Chip } from 'heroui-native';
```
## 结构
```tsx
<Chip>
<Chip.Label>...</Chip.Label>
</Chip>
```
- **Chip**：主容器，展示紧凑元素
- **Chip.Label**：芯片上的文字内容
## 用法
### 基础用法
Chip 以胶囊形态展示文字或自定义内容。
```tsx
<Chip>基础芯片</Chip>
```
### 尺寸
使用 `size` 控制尺寸。
```tsx
<Chip size="sm">小</Chip>
<Chip size="md">中</Chip>
<Chip size="lg">大</Chip>
```
### 变体
使用 `variant` 切换视觉风格。
```tsx
<Chip variant="primary">主要</Chip>
<Chip variant="secondary">次要</Chip>
<Chip variant="tertiary">第三级</Chip>
<Chip variant="soft">柔和</Chip>
```
### 颜色
使用 `color` 应用不同主题色。
```tsx
<Chip color="accent">强调</Chip>
<Chip color="default">默认</Chip>
<Chip color="success">成功</Chip>
<Chip color="warning">警告</Chip>
<Chip color="danger">危险</Chip>
```
### 搭配图标
通过复合组件在文字旁添加图标或自定义内容。
```tsx
<Chip>
<Icon name="star" size={12} />
<Chip.Label>精选</Chip.Label>
</Chip>
<Chip>
<Chip.Label>关闭</Chip.Label>
<Icon name="close" size={12} />
</Chip>
```
### 自定义样式
通过 `className` 或 `style` 传入样式。
```tsx
<Chip className="bg-purple-600 px-6">
<Chip.Label className="text-white">自定义</Chip.Label>
</Chip>
```
### 禁用全部动画
将 `animation` 设为 `"disable-all"` 可禁用自身及子级的全部动画。
```tsx
{
/* 禁用自身及子级的全部动画 */
}
<Chip animation="disable-all">无动画</Chip>;
```
## 示例
```tsx
import { Chip } from 'heroui-native';
import { View, Text } from 'react-native';
import { Ionicons } from '@expo/vector-icons';
export default function ChipExample() {
return (
<View className="gap-4 p-4">
<View className="flex-row flex-wrap gap-2">
<Chip size="sm">小</Chip>
<Chip size="md">中</Chip>
<Chip size="lg">大</Chip>
</View>
<View className="flex-row flex-wrap gap-2">
<Chip variant="primary" color="accent">
主要
</Chip>
<Chip variant="secondary" color="success">
<View className="size-1.5 rounded-full bg-success" />
<Chip.Label>成功</Chip.Label>
</Chip>
<Chip variant="tertiary" color="warning">
<Ionicons name="star" size={12} color="#F59E0B" />
<Chip.Label>高级</Chip.Label>
</Chip>
</View>
<View className="flex-row gap-2">
<Chip variant="secondary">
<Chip.Label>移除</Chip.Label>
<Ionicons name="close" size={14} color="#6B7280" />
</Chip>
<Chip className="bg-purple-600">
<Chip.Label className="text-white font-semibold">自定义</Chip.Label>
</Chip>
</View>
</View>
);
}
```
更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/chip.tsx)。
## API 参考
### Chip
| prop | type | default | description |
| ------------------- | ------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 芯片内要渲染的内容 |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 芯片尺寸 |
| `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'soft'` | `'primary'` | 视觉变体 |
| `color` | `'accent' \| 'default' \| 'success' \| 'warning' \| 'danger'` | `'accent'` | 颜色主题 |
| `className` | `string` | - | 额外的 class |
| `animation` | `"disable-all" \| undefined` | `undefined` | 动画配置；`"disable-all"` 可禁用自身及子级的全部动画 |
| `...PressableProps` | `PressableProps` | - | 支持 `Pressable` 的全部属性 |
### Chip.Label
| prop | type | default | description |
| -------------- | ----------------- | ------- | -------------------------------------- |
| `children` | `React.ReactNode` | - | 作为标签渲染的文字或内容 |
| `className` | `string` | - | 额外的 class |
| `...TextProps` | `TextProps` | - | 支持 React Native `Text` 的全部属性 |
## Hooks
### useChip
访问 Chip 上下文，返回尺寸、变体与颜色。
```tsx
import { useChip } from 'heroui-native';
const { size, variant, color } = useChip();
```
#### 返回值
| property | type | description |
| --------- | ------------------------------------------------------------- | ----------- |
| `size` | `'sm' \| 'md' \| 'lg'` | 芯片尺寸 |
| `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'soft'` | 视觉变体 |
| `color` | `'accent' \| 'default' \| 'success' \| 'warning' \| 'danger'` | 颜色主题 |
**说明：** 必须在 `Chip` 内使用；在上下文外调用将抛出错误。
apps/docs/content/docs/cn/native/components/(feedback)/alert.mdx
+270
View File
@@ -0,0 +1,270 @@
---
title: Alert 警告
description: 向用户展示重要消息与通知，并带有状态指示。
links:
source_native: alert/alert.tsx
styles_native: alert/alert.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/alert-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/alert-docs-dark.mp4"
/>
## 导入
```tsx
import { Alert } from 'heroui-native';
```
## 结构
```tsx
<Alert>
<Alert.Indicator />
<Alert.Content>
<Alert.Title>...</Alert.Title>
<Alert.Description>...</Alert.Description>
</Alert.Content>
</Alert>
```
- **Alert**：根容器，`role="alert"`，按状态应用样式；通过原语上下文向子组件提供状态。
- **Alert.Indicator**：默认渲染与状态匹配的图标；可传入自定义子节点覆盖；支持 `iconProps` 调整尺寸与颜色。
- **Alert.Content**：包裹标题与描述，提供文字布局结构。
- **Alert.Title**：标题文字，颜色随状态变化；通过 `aria-labelledby` 与根关联。
- **Alert.Description**：正文，弱化色；通过 `aria-describedby` 与根关联。
## 用法
### 基础用法
使用复合子部件展示带图标、标题与描述的通知。
```tsx
<Alert>
<Alert.Indicator />
<Alert.Content>
<Alert.Title>新功能已上线</Alert.Title>
<Alert.Description>
查看最新更新，包括深色模式支持与无障碍改进等。
</Alert.Description>
</Alert.Content>
</Alert>
```
### 状态变体
使用 `status` 控制图标与标题颜色。可选：`default`、`accent`、`success`、`warning`、`danger`。
```tsx
<Alert status="success">
<Alert.Indicator />
<Alert.Content>
<Alert.Title>成功</Alert.Title>
<Alert.Description>...</Alert.Description>
</Alert.Content>
</Alert>
<Alert status="warning">
<Alert.Indicator />
<Alert.Content>
<Alert.Title>计划维护</Alert.Title>
<Alert.Description>...</Alert.Description>
</Alert.Content>
</Alert>
<Alert status="danger">
<Alert.Indicator />
<Alert.Content>
<Alert.Title>无法连接</Alert.Title>
<Alert.Description>...</Alert.Description>
</Alert.Content>
</Alert>
```
### 仅标题
省略 `Alert.Description` 以得到紧凑单行提示。
```tsx
<Alert status="success" className="items-center">
<Alert.Indicator className="pt-0" />
<Alert.Content>
<Alert.Title>资料已成功更新</Alert.Title>
</Alert.Content>
</Alert>
```
### 操作按钮
在内容旁放置按钮等额外元素。
```tsx
<Alert status="accent">
<Alert.Indicator />
<Alert.Content>
<Alert.Title>有可用更新</Alert.Title>
<Alert.Description>
应用有新版本可用。
</Alert.Description>
</Alert.Content>
<Button size="sm" variant="primary">
刷新
</Button>
</Alert>
```
### 自定义指示器
向 `Alert.Indicator` 传入自定义子节点以替换默认状态图标。
```tsx
<Alert status="accent">
<Alert.Indicator>
<Spinner>
<Spinner.Indicator iconProps={{ width: 20, height: 20 }} />
</Spinner>
</Alert.Indicator>
<Alert.Content>
<Alert.Title>正在处理请求</Alert.Title>
<Alert.Description>请稍候，正在同步您的数据。</Alert.Description>
</Alert.Content>
</Alert>
```
### 自定义样式
在根与各复合部件上使用 `className`。
```tsx
<Alert className="bg-accent/10 rounded-xl">
<Alert.Indicator className="pt-1" />
<Alert.Content className="gap-1">
<Alert.Title className="text-lg">...</Alert.Title>
<Alert.Description className="text-base">...</Alert.Description>
</Alert.Content>
</Alert>
```
## 示例
```tsx
import { Alert, Button, CloseButton } from 'heroui-native';
import { View } from 'react-native';
export default function AlertExample() {
return (
<View className="w-full gap-4">
<Alert status="accent">
<Alert.Indicator />
<Alert.Content>
<Alert.Title>有可用更新</Alert.Title>
<Alert.Description>
应用有新版本。请刷新以获取最新功能与问题修复。
</Alert.Description>
</Alert.Content>
<Button size="sm" variant="primary">
刷新
</Button>
</Alert>
<Alert status="danger">
<Alert.Indicator />
<Alert.Content>
<Alert.Title>无法连接服务器</Alert.Title>
<Alert.Description>
无法连接到服务器。请检查网络后重试。
</Alert.Description>
</Alert.Content>
<Button size="sm" variant="danger">
重试
</Button>
</Alert>
<Alert status="success" className="items-center">
<Alert.Indicator className="pt-0" />
<Alert.Content>
<Alert.Title>资料已成功更新</Alert.Title>
</Alert.Content>
<CloseButton />
</Alert>
</View>
);
}
```
更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/alert.tsx>)。
## API 参考
### Alert
| prop | type | default | description |
| -------------- | ------------------------------------------------------------- | ----------- | ----------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 渲染在 Alert 内的子节点 |
| `status` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'default'` | 状态，控制图标与着色 |
| `id` | `string \| number` | - | 唯一标识；未提供时自动生成 |
| `className` | `string` | - | 额外的 class |
| `style` | `ViewStyle` | - | 根容器额外样式 |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部属性 |
### Alert.Indicator
| prop | type | default | description |
| -------------- | ----------------- | ------- | ------------------------------------------------------------------ |
| `children` | `React.ReactNode` | - | 自定义子节点，替代默认状态图标 |
| `className` | `string` | - | 额外的 class |
| `iconProps` | `AlertIconProps` | - | 传给默认状态图标的属性（尺寸、颜色等） |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部属性 |
#### AlertIconProps
| prop | type | default | description |
| ------- | -------- | ------------ | ------------------ |
| `size` | `number` | `18` | 图标尺寸（像素） |
| `color` | `string` | 随状态着色 | 图标颜色字符串 |
### Alert.Content
| prop | type | default | description |
| -------------- | ----------------- | ------- | --------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 子节点（通常为 `Alert.Title` 与 `Alert.Description`） |
| `className` | `string` | - | 额外的 class |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部属性 |
### Alert.Title
| prop | type | default | description |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | - | 标题文字 |
| `className` | `string` | - | 额外的 class |
| `...TextProps` | `TextProps` | - | 支持 React Native `Text` 的全部属性 |
### Alert.Description
| prop | type | default | description |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | - | 描述文字 |
| `className` | `string` | - | 额外的 class |
| `...TextProps` | `TextProps` | - | 支持 React Native `Text` 的全部属性 |
## Hooks
### useAlert
访问 Alert 根上下文，必须在 `Alert` 内使用。
```tsx
import { useAlert } from 'heroui-native';
const { status, nativeID } = useAlert();
```
#### 返回值
| property | type | description |
| ---------- | ------------------------------------------------------------- | ---------------------------------------- |
| `status` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | 当前状态，供子组件样式使用 |
| `nativeID` | `string` | 无障碍与 ARIA 使用的唯一标识 |
apps/docs/content/docs/cn/native/components/(feedback)/skeleton-group.mdx
+257
View File
@@ -0,0 +1,257 @@
---
title: SkeletonGroup 骨架屏组
description: 协调多个骨架屏占位，并提供统一的动画与加载态控制。
links:
source_native: skeleton-group/skeleton-group.tsx
styles_native: skeleton-group/skeleton-group.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/skeleton-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/skeleton-docs-dark.mp4"
/>
## 导入
```tsx
import { SkeletonGroup } from 'heroui-native';
```
## 结构
```tsx
<SkeletonGroup>
<SkeletonGroup.Item />
</SkeletonGroup>
```
- **SkeletonGroup**：根容器，为所有骨架项提供统一控制
- **SkeletonGroup.Item**：单个骨架项，继承父级组的属性
## 用法
### 基础用法
SkeletonGroup 用共享的加载态与动画管理多个骨架项。
```tsx
<SkeletonGroup isLoading={isLoading}>
<SkeletonGroup.Item className="h-4 w-full rounded-md" />
<SkeletonGroup.Item className="h-4 w-3/4 rounded-md" />
<SkeletonGroup.Item className="h-4 w-1/2 rounded-md" />
</SkeletonGroup>
```
### 容器布局
在组上使用 `className` 控制骨架项布局。
```tsx
<SkeletonGroup isLoading={isLoading} className="flex-row items-center gap-3">
<SkeletonGroup.Item className="h-12 w-12 rounded-lg" />
<View className="flex-1 gap-1.5">
<SkeletonGroup.Item className="h-4 w-full rounded-md" />
<SkeletonGroup.Item className="h-3 w-2/3 rounded-md" />
</View>
</SkeletonGroup>
```
### isSkeletonOnly（纯骨架布局）
当组内仅有骨架与布局用 `View`（加载完成后无真实内容）时，使用 `isSkeletonOnly`。`isLoading` 为 `false` 时整个组会隐藏，避免空容器影响布局。
```tsx
<SkeletonGroup
isLoading={isLoading}
isSkeletonOnly // isLoading 为 false 时隐藏整组
className="flex-row items-center gap-3"
>
<SkeletonGroup.Item className="h-12 w-12 rounded-lg" />
{/* 该 View 仅用于布局，无加载后内容 */}
<View className="flex-1 gap-1.5">
<SkeletonGroup.Item className="h-4 w-full rounded-md" />
<SkeletonGroup.Item className="h-3 w-2/3 rounded-md" />
</View>
</SkeletonGroup>
```
### 动画变体
为组内所有项统一设置动画变体。
```tsx
<SkeletonGroup isLoading={isLoading} variant="pulse">
<SkeletonGroup.Item className="h-10 w-10 rounded-full" />
<SkeletonGroup.Item className="h-4 w-32 rounded-md" />
<SkeletonGroup.Item className="h-3 w-24 rounded-md" />
</SkeletonGroup>
```
### 自定义动画配置
为整组配置 shimmer 或 pulse。
```tsx
<SkeletonGroup
isLoading={isLoading}
variant="shimmer"
animation={{
shimmer: {
duration: 2000,
highlightColor: 'rgba(59, 130, 246, 0.3)',
},
}}
>
<SkeletonGroup.Item className="h-16 w-full rounded-lg" />
<SkeletonGroup.Item className="h-4 w-3/4 rounded-md" />
</SkeletonGroup>
```
### 进出场动画
组出现或消失时应用 Reanimated 过渡。
```tsx
<SkeletonGroup
entering={FadeInLeft}
exiting={FadeOutRight}
isLoading={isLoading}
className="w-full gap-2"
>
<SkeletonGroup.Item className="h-4 w-full rounded-md" />
<SkeletonGroup.Item className="h-4 w-3/4 rounded-md" />
</SkeletonGroup>
```
## 示例
```tsx
import { Card, SkeletonGroup, Avatar } from 'heroui-native';
import { useState } from 'react';
import { Text, View, Image } from 'react-native';
export default function SkeletonGroupExample() {
const [isLoading, setIsLoading] = useState(true);
return (
<SkeletonGroup isLoading={isLoading}>
<Card className="p-4">
<Card.Header>
<View className="flex-row items-center gap-3 mb-4">
<SkeletonGroup.Item className="h-10 w-10 rounded-full">
<Avatar size="sm" alt="Avatar">
<Avatar.Image
source={{ uri: 'https://i.pravatar.cc/150?img=4' }}
/>
<Avatar.Fallback />
</Avatar>
</SkeletonGroup.Item>
<View className="flex-1 gap-1">
<SkeletonGroup.Item className="h-3 w-32 rounded-md">
<Text className="font-semibold text-foreground">John Doe</Text>
</SkeletonGroup.Item>
<SkeletonGroup.Item className="h-3 w-24 rounded-md">
<Text className="text-sm text-muted">@johndoe</Text>
</SkeletonGroup.Item>
</View>
</View>
<View className="mb-4 gap-1.5">
<SkeletonGroup.Item className="h-4 w-full rounded-md">
<Text className="text-base text-foreground">
This is the first line of the post content.
</Text>
</SkeletonGroup.Item>
<SkeletonGroup.Item className="h-4 w-full rounded-md">
<Text className="text-base text-foreground">
Second line with more interesting content to read.
</Text>
</SkeletonGroup.Item>
<SkeletonGroup.Item className="h-4 w-2/3 rounded-md">
<Text className="text-base text-foreground">
Last line is shorter.
</Text>
</SkeletonGroup.Item>
</View>
</Card.Header>
<SkeletonGroup.Item className="h-48 w-full rounded-lg">
<View className="h-48 bg-surface-tertiary rounded-lg overflow-hidden">
<Image
source={{
uri: 'https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/backgrounds/cards/car1.jpg',
}}
className="h-full w-full"
/>
</View>
</SkeletonGroup.Item>
</Card>
</SkeletonGroup>
);
}
```
更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/skeleton-group.tsx)。
## API 参考
### SkeletonGroup
| prop | type | default | description |
| ----------------------- | -------------------------------- | ----------- | ---------------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | `SkeletonGroup.Item` 与布局元素 |
| `isLoading` | `boolean` | `true` | 骨架项是否处于加载中 |
| `isSkeletonOnly` | `boolean` | `false` | 为 `true` 时，`isLoading` 为 `false` 隐藏整组（纯骨架布局） |
| `variant` | `'shimmer' \| 'pulse' \| 'none'` | `'shimmer'` | 组内所有项的动画变体 |
| `animation` | `SkeletonRootAnimation` | - | 动画配置 |
| `className` | `string` | - | 组容器额外 class |
| `style` | `StyleProp<ViewStyle>` | - | 组容器自定义样式 |
| `...Animated.ViewProps` | `AnimatedProps<ViewProps>` | - | 支持 Reanimated `Animated.View` 全部属性 |
#### SkeletonRootAnimation
SkeletonGroup 动画配置，可为：
- `false` 或 `"disabled"`：仅关闭根动画
- `"disable-all"`：关闭所有动画（含子级）
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| ------------------------ | ---------------------------------------- | --------------------------- | ----------------------------------------------- |
| `state` | `'disabled' \| 'disable-all' \| boolean` | - | 关闭动画的同时仍允许自定义属性 |
| `entering.value` | `EntryOrExitLayoutType` | `FadeIn` | 自定义进入动画 |
| `exiting.value` | `EntryOrExitLayoutType` | `FadeOut` | 自定义退出动画 |
| `shimmer.duration` | `number` | `1500` | 动画时长（毫秒） |
| `shimmer.speed` | `number` | `1` | 速度倍率 |
| `shimmer.highlightColor` | `string` | - | 微光高光色 |
| `shimmer.easing` | `EasingFunction` | `Easing.linear` | 缓动函数 |
| `pulse.duration` | `number` | `1000` | 动画时长（毫秒） |
| `pulse.minOpacity` | `number` | `0.5` | 最小不透明度 |
| `pulse.maxOpacity` | `number` | `1` | 最大不透明度 |
| `pulse.easing` | `EasingFunction` | `Easing.inOut(Easing.ease)` | 缓动函数 |
### SkeletonGroup.Item
| prop | type | default | description |
| ----------------------- | -------------------------------- | --------- | ------------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 非加载态显示的内容 |
| `isLoading` | `boolean` | 继承组 | 是否加载中（覆盖组设置） |
| `variant` | `'shimmer' \| 'pulse' \| 'none'` | 继承组 | 动画变体（覆盖组设置） |
| `animation` | `SkeletonRootAnimation` | 继承组 | 动画配置（覆盖组设置） |
| `className` | `string` | - | 单项额外 class |
| `...Animated.ViewProps` | `AnimatedProps<ViewProps>` | - | 支持 Reanimated `Animated.View` 全部属性 |
## 特别说明
### 属性继承
`SkeletonGroup.Item` 从父级 `SkeletonGroup` 继承所有与动画相关的属性：
- `isLoading`
- `variant`
- `animation`
单项可通过自身属性覆盖继承值。
apps/docs/content/docs/cn/native/components/(feedback)/skeleton.mdx
+218
View File
@@ -0,0 +1,218 @@
---
title: Skeleton 骨架屏
description: 展示加载占位，支持微光（shimmer）或脉冲（pulse）等动画效果。
links:
source_native: skeleton/skeleton.tsx
styles_native: skeleton/skeleton.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/skeleton-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/skeleton-docs-dark.mp4"
/>
## 导入
```tsx
import { Skeleton } from 'heroui-native';
```
## 结构
Skeleton 为简单包装器，在内容加载时渲染占位，无子部件 API。
```tsx
<Skeleton />
```
## 用法
### 基础用法
在内容加载期间显示带动画的占位。
```tsx
<Skeleton className="h-20 w-full rounded-lg" />
```
### 与内容切换
加载中显示 Skeleton，就绪后显示真实内容。
```tsx
<Skeleton isLoading={isLoading} className="h-20 rounded-lg">
<View className="h-20 bg-primary rounded-lg">
<Text>Loaded Content</Text>
</View>
</Skeleton>
```
### 动画变体
用 `variant` 控制动画样式。
```tsx
<Skeleton variant="shimmer" className="h-20 w-full rounded-lg" />
<Skeleton variant="pulse" className="h-20 w-full rounded-lg" />
<Skeleton variant="none" className="h-20 w-full rounded-lg" />
```
### 自定义微光
自定义时长、速度与高光色。
```tsx
<Skeleton
className="h-16 w-full rounded-lg"
variant="shimmer"
animation={{
shimmer: {
duration: 2000,
speed: 2,
highlightColor: 'rgba(59, 130, 246, 0.3)',
},
}}
>
...
</Skeleton>
```
### 自定义脉冲
配置脉冲时长与不透明度范围。
```tsx
<Skeleton
className="h-16 w-full rounded-lg"
variant="pulse"
animation={{
pulse: {
duration: 500,
minOpacity: 0.1,
maxOpacity: 0.8,
},
}}
>
...
</Skeleton>
```
### 形状变化
通过 `className` 控制占位形状。
```tsx
<Skeleton className="h-4 w-full rounded-md" />
<Skeleton className="h-4 w-3/4 rounded-md" />
<Skeleton className="h-4 w-1/2 rounded-md" />
<Skeleton className="size-12 rounded-full" />
```
### 自定义进出场
Skeleton 出现或消失时使用自定义 Reanimated 过渡。
```tsx
<Skeleton
entering={FadeIn.duration(300)}
exiting={FadeOut.duration(300)}
isLoading={isLoading}
className="h-20 w-full rounded-lg"
>
...
</Skeleton>
```
## 示例
```tsx
import { Avatar, Card, Skeleton } from 'heroui-native';
import { useState } from 'react';
import { Image, Text, View } from 'react-native';
export default function SkeletonExample() {
const [isLoading, setIsLoading] = useState(true);
return (
<Card className="p-4">
<View className="flex-row items-center gap-3 mb-4">
<Skeleton isLoading={isLoading} className="h-10 w-10 rounded-full">
<Avatar size="sm" alt="Avatar">
<Avatar.Image source={{ uri: 'https://i.pravatar.cc/150?img=4' }} />
<Avatar.Fallback />
</Avatar>
</Skeleton>
<View className="flex-1 gap-1">
<Skeleton isLoading={isLoading} className="h-3 w-32 rounded-md">
<Text className="font-semibold text-foreground">John Doe</Text>
</Skeleton>
<Skeleton isLoading={isLoading} className="h-3 w-24 rounded-md">
<Text className="text-sm text-muted">@johndoe</Text>
</Skeleton>
</View>
</View>
<Skeleton
isLoading={isLoading}
className="h-48 w-full rounded-lg"
animation={{
shimmer: {
duration: 1500,
speed: 1,
},
}}
>
<View className="h-48 bg-surface-tertiary rounded-lg overflow-hidden">
<Image
source={{
uri: 'https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/backgrounds/cards/car1.jpg',
}}
className="h-full w-full"
/>
</View>
</Skeleton>
</Card>
);
}
```
更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/skeleton.tsx)。
## API 参考
### Skeleton
| prop | type | default | description |
| ----------------------- | -------------------------------- | ----------- | ------------------------------------------------------------ |
| `children` | `React.ReactNode` | - | 非加载态时显示的内容 |
| `isLoading` | `boolean` | `true` | 是否处于加载中 |
| `variant` | `'shimmer' \| 'pulse' \| 'none'` | `'shimmer'` | 动画变体 |
| `animation` | `SkeletonRootAnimation` | - | 动画配置 |
| `isAnimatedStyleActive` | `boolean` | `true` | 是否启用 Reanimated 动画样式 |
| `className` | `string` | - | 额外样式 class |
| `...Animated.ViewProps` | `AnimatedProps<ViewProps>` | - | 支持 Reanimated `Animated.View` 的全部属性 |
#### SkeletonRootAnimation
Skeleton 根动画配置，可为：
- `false` 或 `"disabled"`：仅关闭根动画
- `"disable-all"`：关闭所有动画（含子级）
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| ------------------------ | ---------------------------------------- | --------------------------- | ----------------------------------------------- |
| `state` | `'disabled' \| 'disable-all' \| boolean` | - | 关闭动画的同时仍允许自定义属性 |
| `entering.value` | `EntryOrExitLayoutType` | `FadeIn` | 自定义进入动画 |
| `exiting.value` | `EntryOrExitLayoutType` | `FadeOut` | 自定义退出动画 |
| `shimmer.duration` | `number` | `1500` | 动画时长（毫秒） |
| `shimmer.speed` | `number` | `1` | 速度倍率 |
| `shimmer.highlightColor` | `string` | - | 微光高光色 |
| `shimmer.easing` | `EasingFunction` | `Easing.linear` | 缓动函数 |
| `pulse.duration` | `number` | `1000` | 动画时长（毫秒） |
| `pulse.minOpacity` | `number` | `0.5` | 最小不透明度 |
| `pulse.maxOpacity` | `number` | `1` | 最大不透明度 |
| `pulse.easing` | `EasingFunction` | `Easing.inOut(Easing.ease)` | 缓动函数 |
apps/docs/content/docs/cn/native/components/(feedback)/spinner.mdx
+209
View File
@@ -0,0 +1,209 @@
---
title: Spinner 加载指示器
description: 展示旋转加载动画。
links:
source_native: spinner/spinner.tsx
styles_native: spinner/spinner.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/spinner-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/spinner-docs-dark.mp4"
/>
## 导入
```tsx
import { Spinner } from 'heroui-native';
```
## 结构
```tsx
<Spinner>
<Spinner.Indicator>...</Spinner.Indicator>
</Spinner>
```
- **Spinner**：主容器，控制加载状态、尺寸与颜色。未提供子节点时渲染默认动画指示器。
- **Spinner.Indicator**：可选子组件，用于自定义动画配置与图标外观；可传入自定义子节点替换默认图标。
## 用法
### 基础用法
展示旋转加载指示器。
```tsx
<Spinner />
```
### 尺寸
使用 `size` 控制大小。
```tsx
<Spinner size="sm" />
<Spinner size="md" />
<Spinner size="lg" />
```
### 颜色
使用预设色或自定义颜色字符串。
```tsx
<Spinner color="default" />
<Spinner color="success" />
<Spinner color="warning" />
<Spinner color="danger" />
<Spinner color="#8B5CF6" />
```
### 加载状态
使用 `isLoading` 控制是否显示。
```tsx
<Spinner isLoading={true} />
<Spinner isLoading={false} />
```
### 动画速度
在 `Indicator` 上使用 `animation` 自定义旋转速度。
```tsx
<Spinner>
<Spinner.Indicator animation={{ rotation: { speed: 0.5 } }} />
</Spinner>
<Spinner>
<Spinner.Indicator animation={{ rotation: { speed: 2 } }} />
</Spinner>
```
### 自定义图标
用自定义内容替换默认图标。
```tsx
const themeColorForeground = useThemeColor('foreground')
<Spinner>
<Spinner.Indicator>
<Ionicons name="refresh" size={24} color={themeColorForeground} />
</Spinner.Indicator>
</Spinner>
<Spinner>
<Spinner.Indicator>
<Text>⏳</Text>
</Spinner.Indicator>
</Spinner>
```
## 示例
```tsx
import { Spinner } from 'heroui-native';
import { Ionicons } from '@expo/vector-icons';
import React from 'react';
import { Text, TouchableOpacity, View } from 'react-native';
export default function SpinnerExample() {
const [isLoading, setIsLoading] = React.useState(true);
return (
<View className="gap-4 p-4 bg-background">
<View className="flex-row items-center gap-2 p-4 rounded-lg bg-stone-200">
<Spinner size="sm" color="default" />
<Text className="text-stone-500">正在加载内容…</Text>
</View>
<View className="items-center p-8 rounded-2xl bg-stone-200">
<Spinner size="lg" color="success" isLoading={isLoading} />
<Text className="text-stone-500 mt-4">处理中…</Text>
<TouchableOpacity onPress={() => setIsLoading(!isLoading)}>
<Text className="text-primary mt-2 text-sm">
{isLoading ? '点击停止' : '点击开始'}
</Text>
</TouchableOpacity>
</View>
<View className="flex-row gap-4 items-center justify-center">
<Spinner size="md" color="#EC4899">
<Spinner.Indicator animation={{ rotation: { speed: 0.7 } }}>
<Ionicons name="refresh" size={24} color="#EC4899" />
</Spinner.Indicator>
</Spinner>
</View>
</View>
);
}
```
更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/spinner.tsx)。
## API 参考
### Spinner
| prop | type | default | description |
| -------------- | ----------------------------------------------------------- | ----------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | `undefined` | 旋转器内部内容 |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 尺寸 |
| `color` | `'default' \| 'success' \| 'warning' \| 'danger' \| string` | `'default'` | 颜色主题或自定义色值 |
| `isLoading` | `boolean` | `true` | 是否处于加载中（显示动画） |
| `className` | `string` | `undefined` | 自定义 class |
| `animation` | `SpinnerRootAnimation` | - | 根级动画配置 |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部属性 |
#### SpinnerRootAnimation
Spinner 根组件的动画配置，可为：
- `false` 或 `"disabled"`：仅禁用根级动画
- `"disable-all"`：禁用全部动画（含子级）
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| ---------------- | ---------------------------------------- | -------------------------------------------------------------------- | --------------------------------- |
| `state` | `'disabled' \| 'disable-all' \| boolean` | - | 在自定义属性时禁用动画 |
| `entering.value` | `EntryOrExitLayoutType` | `FadeIn`<br/>`.duration(200)`<br/>`.easing(Easing.out(Easing.ease))` | 自定义进入动画 |
| `exiting.value` | `EntryOrExitLayoutType` | `FadeOut`<br/>`.duration(100)` | 自定义退出动画 |
### Spinner.Indicator
| prop | type | default | description |
| ----------------------- | --------------------------- | ----------- | ------------------------------------------------------------ |
| `children` | `React.ReactNode` | `undefined` | 指示器内部内容 |
| `iconProps` | `SpinnerIconProps` | `undefined` | 默认图标的属性 |
| `className` | `string` | `undefined` | 指示器元素的 class |
| `animation` | `SpinnerIndicatorAnimation` | - | 动画配置 |
| `isAnimatedStyleActive` | `boolean` | `true` | 是否启用 Reanimated 动画样式 |
| `...Animated.ViewProps` | `Animated.ViewProps` | - | 支持 Reanimated `Animated.View` 的全部属性 |
#### SpinnerIndicatorAnimation
`Spinner.Indicator` 的动画配置，可为：
- `false` 或 `"disabled"`：禁用全部动画
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| ----------------- | ---------------------------- | --------------- | --------------------------------- |
| `state` | `'disabled' \| boolean` | - | 在自定义属性时禁用动画 |
| `rotation.speed` | `number` | `1.1` | 旋转速度倍率 |
| `rotation.easing` | `WithTimingConfig['easing']` | `Easing.linear` | 动画缓动配置 |
### SpinnerIconProps
| prop | type | default | description |
| -------- | ------------------ | ---------------- | ----------- |
| `width` | `number \| string` | `24` | 图标宽度 |
| `height` | `number \| string` | `24` | 图标高度 |
| `color` | `string` | `'currentColor'` | 图标颜色 |
apps/docs/content/docs/cn/native/components/(forms)/checkbox.mdx
+323
View File
@@ -0,0 +1,323 @@
---
title: Checkbox 复选框
description: 可在选中与未选中之间切换的可选控件。
links:
source_native: checkbox/checkbox.tsx
styles_native: checkbox/checkbox.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/checkbox-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/checkbox-docs-dark.mp4"
/>
## 导入
```tsx
import { Checkbox } from 'heroui-native';
```
## 结构
```tsx
<Checkbox>
<Checkbox.Indicator>...</Checkbox.Indicator>
</Checkbox>
```
- **Checkbox**：主容器，处理选中状态与用户交互。未提供子节点时渲染带动画对勾的默认指示器；自动识别是否在 Surface 上以便样式正确；支持可定制或关闭的按压缩放动画；子节点可为渲染函数以访问 `isSelected`、`isInvalid`、`isDisabled`。
- **Checkbox.Indicator**：可选对勾容器，选中时默认带滑动、缩放、透明度与圆角动画；无子节点时渲染带动画路径的 SVG 对勾；各动画可单独配置或关闭；子节点可为渲染函数以访问状态。
## 用法
### 基础用法
未提供子节点时，Checkbox 使用默认动画指示器，并自动检测是否在 Surface 背景上。
```tsx
<Checkbox isSelected={isSelected} onSelectedChange={setIsSelected} />
```
### 自定义指示器
在 Indicator 中使用渲染函数，按状态显示/隐藏自定义图标。
```tsx
<Checkbox isSelected={isSelected} onSelectedChange={setIsSelected}>
<Checkbox.Indicator>
{({ isSelected }) => (isSelected ? <CheckIcon /> : null)}
</Checkbox.Indicator>
</Checkbox>
```
### 非法状态
使用 `isInvalid` 表示校验错误并应用危险色样式。
```tsx
<Checkbox
isSelected={isSelected}
onSelectedChange={setIsSelected}
isInvalid={hasError}
/>
```
### 自定义动画
为根与指示器分别自定义或关闭动画。
```tsx
{
/* 关闭所有动画（根与指示器） */
}
<Checkbox
animation="disable-all"
isSelected={isSelected}
onSelectedChange={setIsSelected}
>
<Checkbox.Indicator />
</Checkbox>;
{
/* 仅关闭根动画 */
}
<Checkbox
animation="disabled"
isSelected={isSelected}
onSelectedChange={setIsSelected}
>
<Checkbox.Indicator />
</Checkbox>;
{
/* 仅关闭指示器动画 */
}
<Checkbox isSelected={isSelected} onSelectedChange={setIsSelected}>
<Checkbox.Indicator animation="disabled" />
</Checkbox>;
{
/* 自定义动画配置 */
}
<Checkbox
animation={{ scale: { value: [1, 0.9], timingConfig: { duration: 200 } } }}
isSelected={isSelected}
onSelectedChange={setIsSelected}
>
<Checkbox.Indicator
animation={{
scale: { value: [0.5, 1] },
opacity: { value: [0, 1] },
translateX: { value: [-8, 0] },
borderRadius: { value: [12, 0] },
}}
/>
</Checkbox>;
```
## 示例
```tsx
import {
Checkbox,
Description,
ControlField,
Label,
Separator,
Surface,
} from "heroui-native";
import React from 'react';
import { View, Text } from 'react-native';
interface CheckboxFieldProps {
isSelected: boolean;
onSelectedChange: (value: boolean) => void;
title: string;
description: string;
}
const CheckboxField: React.FC<CheckboxFieldProps> = ({
isSelected,
onSelectedChange,
title,
description,
}) => {
return (
<ControlField isSelected={isSelected} onSelectedChange={onSelectedChange}>
<ControlField.Indicator>
<Checkbox className="mt-0.5" />
</ControlField.Indicator>
<View className="flex-1">
<Label className="text-lg">{title}</Label>
<Description className="text-base">
{description}
</Description>
</View>
</ControlField>
);
};
export default function BasicUsage() {
const [fields, setFields] = React.useState({
newsletter: true,
marketing: false,
terms: false,
});
const fieldConfigs: Record<
keyof typeof fields,
{ title: string; description: string }
> = {
newsletter: {
title: 'Subscribe to newsletter',
description: 'Get weekly updates about new features and tips',
},
marketing: {
title: 'Marketing communications',
description: 'Receive promotional emails and special offers',
},
terms: {
title: 'Accept terms and conditions',
description: 'Agree to our Terms of Service and Privacy Policy',
},
};
const handleFieldChange = (key: keyof typeof fields) => (value: boolean) => {
setFields((prev) => ({ ...prev, [key]: value }));
};
const fieldKeys = Object.keys(fields) as Array<keyof typeof fields>;
return (
<View className="flex-1 items-center justify-center px-5">
<Surface className="py-5 w-full">
{fieldKeys.map((key, index) => (
<React.Fragment key={key}>
{index > 0 && <Separator className="my-4" />}
<CheckboxField
isSelected={fields[key]}
onSelectedChange={handleFieldChange(key)}
title={fieldConfigs[key].title}
description={fieldConfigs[key].description}
/>
</React.Fragment>
))}
</Surface>
</View>
);
}
```
更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/checkbox.tsx>)。
## API 参考
### Checkbox
| prop | type | default | description |
| ----------------------- | ---------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------- |
| `children` | `React.ReactNode \| ((props: CheckboxRenderProps) => React.ReactNode)` | `undefined` | 子元素或用于自定义的渲染函数 |
| `isSelected` | `boolean` | `undefined` | 是否选中 |
| `onSelectedChange` | `(isSelected: boolean) => void` | `undefined` | 选中状态变化时回调 |
| `isDisabled` | `boolean` | `false` | 是否禁用、不可交互 |
| `isInvalid` | `boolean` | `false` | 是否非法（危险色样式） |
| `variant` | `'primary' \| 'secondary'` | `'primary'` | 视觉变体 |
| `hitSlop` | `number` | `6` | 可点区域扩展（hit slop） |
| `animation` | `CheckboxRootAnimation` | - | 动画配置 |
| `isAnimatedStyleActive` | `boolean` | `true` | 是否启用 Reanimated 动画样式 |
| `className` | `string` | `undefined` | 额外 class |
| `...PressableProps` | `PressableProps` | - | 支持 React Native `Pressable` 标准属性（`disabled` 除外） |
#### CheckboxRenderProps
| prop | type | description |
| ------------ | --------- | -------------------------------- |
| `isSelected` | `boolean` | 是否选中 |
| `isInvalid` | `boolean` | 是否非法 |
| `isDisabled` | `boolean` | 是否禁用 |
#### CheckboxRootAnimation
复选框根组件动画配置，可为：
- `false` 或 `"disabled"`：仅关闭根动画
- `"disable-all"`：关闭所有动画（含子级）
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| -------------------- | ---------------------------------------- | ------------------- | ----------------------------------------------- |
| `state` | `'disabled' \| 'disable-all' \| boolean` | - | 关闭动画的同时仍允许自定义属性 |
| `scale.value` | `[number, number]` | `[1, 0.96]` | 缩放值 [未按压, 按压] |
| `scale.timingConfig` | `WithTimingConfig` | `{ duration: 150 }` | 动画时间配置 |
### Checkbox.Indicator
| prop | type | default | description |
| ----------------------- | ---------------------------------------------------------------------- | ----------- | ------------------------------------------------------------ |
| `children` | `React.ReactNode \| ((props: CheckboxRenderProps) => React.ReactNode)` | `undefined` | 指示器内容或渲染函数 |
| `className` | `string` | `undefined` | 指示器额外 class |
| `iconProps` | `CheckboxIndicatorIconProps` | `undefined` | 默认动画对勾图标的自定义属性 |
| `animation` | `CheckboxIndicatorAnimation` | - | 动画配置 |
| `isAnimatedStyleActive` | `boolean` | `true` | 是否启用 Reanimated 动画样式 |
| `...AnimatedViewProps` | `AnimatedProps<ViewProps>` | - | 支持 React Native Animated View 标准属性 |
#### CheckboxIndicatorIconProps
用于自定义默认动画对勾图标。
| prop | type | description |
| --------------- | -------- | ------------------------------------------------ |
| `size` | `number` | 图标尺寸 |
| `strokeWidth` | `number` | 描边宽度 |
| `color` | `string` | 图标颜色（默认为主题 accent-foreground） |
| `enterDuration` | `number` | 出现动画时长（对勾显示） |
| `exitDuration` | `number` | 消失动画时长（对勾隐藏） |
#### CheckboxIndicatorAnimation
指示器动画配置，可为：
- `false` 或 `"disabled"`：关闭全部动画
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| --------------------------- | ----------------------- | ------------------- | ----------------------------------------------- |
| `state` | `'disabled' \| boolean` | - | 关闭动画的同时仍允许自定义属性 |
| `opacity.value` | `[number, number]` | `[0, 1]` | 透明度 [未选中, 选中] |
| `opacity.timingConfig` | `WithTimingConfig` | `{ duration: 100 }` | 透明度动画时间配置 |
| `borderRadius.value` | `[number, number]` | `[8, 0]` | 圆角 [未选中, 选中] |
| `borderRadius.timingConfig` | `WithTimingConfig` | `{ duration: 50 }` | 圆角动画时间配置 |
| `translateX.value` | `[number, number]` | `[-4, 0]` | X 位移 [未选中, 选中] |
| `translateX.timingConfig` | `WithTimingConfig` | `{ duration: 100 }` | 位移动画时间配置 |
| `scale.value` | `[number, number]` | `[0.8, 1]` | 缩放 [未选中, 选中] |
| `scale.timingConfig` | `WithTimingConfig` | `{ duration: 100 }` | 缩放动画时间配置 |
## Hooks
### useCheckbox
在自定义或复合结构内访问复选框上下文。
```tsx
import { useCheckbox } from 'heroui-native';
const CustomIndicator = () => {
const { isSelected, isInvalid, isDisabled } = useCheckbox();
// ... your implementation
};
```
**返回值：** `UseCheckboxReturn`
| property | type | description |
| ------------------ | ---------------------------------------------- | -------------------------------------------------------------- |
| `isSelected` | `boolean \| undefined` | 是否选中 |
| `onSelectedChange` | `((isSelected: boolean) => void) \| undefined` | 修改选中状态的回调函数 |
| `isDisabled` | `boolean` | 是否禁用、不可交互 |
| `isInvalid` | `boolean` | 是否非法（危险色） |
| `nativeID` | `string \| undefined` | 复选框元素 native ID |
**注意：** 必须在 `Checkbox` 内使用；在上下文外调用会抛错。
apps/docs/content/docs/cn/native/components/(forms)/control-field.mdx
+253
View File
@@ -0,0 +1,253 @@
---
title: ControlField 控件字段
description: 将标签、说明（或其他内容）与控件（Switch 或 Checkbox）组合为单一可按压区域的字段组件。
links:
source_native: control-field/control-field.tsx
styles_native: control-field/control-field.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/control-field-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/control-field-docs-dark.mp4"
/>
## 导入
```tsx
import { ControlField } from 'heroui-native';
```
## 结构
```tsx
<ControlField>
<Label>...</Label>
<Description>...</Description>
<ControlField.Indicator>...</ControlField.Indicator>
<FieldError>...</FieldError>
</ControlField>
```
- **ControlField**：根容器，管理布局与状态向下传递
- **Label**：主标签（来自 [Label](./label)）
- **Description**：辅助说明（来自 [Description](./description)）
- **ControlField.Indicator**：表单控件容器（[Switch](./switch)、[Checkbox](./checkbox)、[Radio](./radio)）
- **FieldError**：校验错误展示（来自 [FieldError](./field-error)）
## 用法
### 基础用法
ControlField 包裹控件，提供一致布局与状态管理。
```tsx
<ControlField isSelected={value} onSelectedChange={setValue}>
<Label className="flex-1">Label text</Label>
<ControlField.Indicator />
</ControlField>
```
### 带说明
在标签下使用 Description 添加辅助说明。
```tsx
<ControlField isSelected={value} onSelectedChange={setValue}>
<View className="flex-1">
<Label>Enable notifications</Label>
<Description>
Receive push notifications about your account activity
</Description>
</View>
<ControlField.Indicator />
</ControlField>
```
### 带错误信息
使用 FieldError 展示校验错误。
```tsx
<ControlField
isSelected={value}
onSelectedChange={setValue}
isInvalid={!value}
className="flex-col items-start gap-1"
>
<View className="flex-row items-center gap-2">
<View className="flex-1">
<Label>I agree to the terms</Label>
<Description>
By checking this box, you agree to our Terms of Service
</Description>
</View>
<ControlField.Indicator variant="checkbox" />
</View>
<FieldError>This field is required</FieldError>
</ControlField>
```
### 禁用态
使用 `isDisabled` 控制是否可交互。
```tsx
<ControlField isSelected={value} onSelectedChange={setValue} isDisabled>
<View className="flex-1">
<Label>Disabled field</Label>
<Description>This field is disabled</Description>
</View>
<ControlField.Indicator />
</ControlField>
```
### 关闭所有动画
使用 `"disable-all"` 关闭根及子级全部动画。
```tsx
<ControlField
isSelected={value}
onSelectedChange={setValue}
animation="disable-all"
>
<View className="flex-1">
<Label>Label text</Label>
<Description>Description text</Description>
</View>
<ControlField.Indicator />
</ControlField>
```
## 示例
```tsx
import {
Checkbox,
Description,
FieldError,
ControlField,
Label,
Switch,
} from 'heroui-native';
import React from 'react';
import { ScrollView, View } from 'react-native';
export default function ControlFieldExample() {
const [notifications, setNotifications] = React.useState(false);
const [terms, setTerms] = React.useState(false);
const [newsletter, setNewsletter] = React.useState(true);
return (
<ScrollView className="bg-background p-4">
<View className="gap-4">
<ControlField
isSelected={notifications}
onSelectedChange={setNotifications}
>
<View className="flex-1">
<Label>Enable notifications</Label>
<Description>
Receive push notifications about your account activity
</Description>
</View>
<ControlField.Indicator />
</ControlField>
<ControlField
isSelected={terms}
onSelectedChange={setTerms}
isInvalid={!terms}
className="flex-col items-start gap-1"
>
<View className="flex-row items-center gap-2">
<View className="flex-1">
<Label>I agree to the terms and conditions</Label>
<Description>
By checking this box, you agree to our Terms of Service
</Description>
</View>
<ControlField.Indicator className="mt-0.5">
<Checkbox />
</ControlField.Indicator>
</View>
<FieldError>This field is required</FieldError>
</ControlField>
<ControlField isSelected={newsletter} onSelectedChange={setNewsletter}>
<View className="flex-1">
<Label>Subscribe to newsletter</Label>
</View>
<ControlField.Indicator>
<Checkbox color="warning" />
</ControlField.Indicator>
</ControlField>
</View>
</ScrollView>
);
}
```
更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/control-field.tsx)。
## API 参考
### ControlField
| prop | type | default | description |
| ----------------- | -------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
| children | `React.ReactNode \| ((props: ControlFieldRenderProps) => React.ReactNode)` | - | 字段内部内容或渲染函数 |
| isSelected | `boolean` | `undefined` | 是否选中/勾选 |
| isDisabled | `boolean` | `false` | 是否禁用 |
| isInvalid | `boolean` | `false` | 是否非法 |
| isRequired | `boolean` | `false` | 是否必填 |
| className | `string` | - | 根元素自定义 class |
| onSelectedChange | `(isSelected: boolean) => void` | - | 选中状态变化时回调 |
| animation | `"disable-all" \| undefined` | `undefined` | 动画配置；`"disable-all"` 时关闭根及子级全部动画 |
| ...PressableProps | `PressableProps` | - | 支持 React Native Pressable 全部属性 |
### Label
`Label` 会自动消费 ControlField 上下文中的表单状态（`isDisabled`、`isInvalid`）。
**说明**：完整属性见 [Label 组件文档](./label)。
### Description
`Description` 会自动消费 ControlField 上下文中的表单状态（`isDisabled`、`isInvalid`）。
**说明**：完整属性见 [Description 组件文档](./description)。
### ControlField.Indicator
| prop | type | default | description |
| ------------ | ----------------------------------- | ---------- | ---------------------------------------------------------- |
| children | `React.ReactNode` | - | 要渲染的控件（Switch、Checkbox、Radio） |
| variant | `'checkbox' \| 'radio' \| 'switch'` | `'switch'` | 未提供 children 时渲染的内置变体 |
| className | `string` | - | 指示器容器自定义 class |
| ...ViewProps | `ViewProps` | - | 支持 React Native View 全部属性 |
**说明：** 提供 `children` 时，若子组件上尚未设置，会自动从 ControlField 上下文传入 `isSelected`、`onSelectedChange`、`isDisabled`、`isInvalid`。使用 `radio` 变体时，Radio 以独立模式渲染（不在 RadioGroup 内）。
### FieldError
`FieldError` 会自动消费 ControlField 上下文中的 `isInvalid`。
**说明**：完整属性见 [FieldError 组件文档](./field-error)。显隐由父级 ControlField 的 `isInvalid` 控制。
## Hooks
### useControlField
在 `ControlField` 内访问字段上下文（用于自定义子结构）。
**返回值：**
| property | type | description |
| ------------------ | ---------------------------------------------- | ---------------------------------------------- |
| `isSelected` | `boolean \| undefined` | 是否选中/勾选 |
| `onSelectedChange` | `((isSelected: boolean) => void) \| undefined` | 选中状态变化回调 |
| `isDisabled` | `boolean` | 是否禁用 |
| `isInvalid` | `boolean` | 是否非法 |
| `isPressed` | `SharedValue<boolean>` | Reanimated 共享值，表示按压状态 |
apps/docs/content/docs/cn/native/components/(forms)/description.mdx
+139
View File
@@ -0,0 +1,139 @@
---
title: Description 描述
description: 用于为表单字段等提供无障碍说明与辅助文案的文本组件。
links:
source_native: description/description.tsx
styles_native: description/description.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/description-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/description-docs-dark.mp4"
/>
## 导入
```tsx
import { Description } from 'heroui-native';
```
## 结构
```tsx
<Description>...</Description>
```
- **Description**：以弱化样式展示说明或辅助文案；可通过 `nativeID` 与表单字段关联以支持无障碍。
## 用法
### 基础用法
使用默认弱化样式展示说明文字。
```tsx
<Description>This is a helpful description.</Description>
```
### 与表单字段组合
使用 `nativeID` 为表单字段提供可关联的说明。
```tsx
<TextField>
<Label>Email address</Label>
<Input
placeholder="Enter your email"
keyboardType="email-address"
autoCapitalize="none"
/>
<Description nativeID="email-desc">
We'll never share your email with anyone else.
</Description>
</TextField>
```
### 无障碍关联
通过 `nativeID` 与 `aria-describedby` 将说明与字段关联，便于读屏。
```tsx
<TextField>
<Label>Password</Label>
<Input
placeholder="Create a password"
secureTextEntry
aria-describedby="password-desc"
/>
<Description nativeID="password-desc">
Use at least 8 characters with a mix of letters, numbers, and symbols.
</Description>
</TextField>
```
### 非法态时隐藏
使用 `hideOnInvalid` 控制字段非法时是否隐藏说明。
```tsx
<TextField isInvalid={isInvalid}>
<Label>Email</Label>
<Input placeholder="Enter your email" />
<Description hideOnInvalid>
We'll never share your email with anyone else.
</Description>
<FieldError>Please enter a valid email address</FieldError>
</TextField>
```
当 `hideOnInvalid` 为 `true` 时，字段非法会隐藏说明；为 `false`（默认）时非法仍显示说明。
## 示例
```tsx
import { Description, Input, Label, TextField } from 'heroui-native';
import { View } from 'react-native';
export default function DescriptionExample() {
return (
<View className="flex-1 justify-center px-5 gap-8">
<TextField>
<Label>Email address</Label>
<Input
placeholder="Enter your email"
keyboardType="email-address"
autoCapitalize="none"
/>
<Description nativeID="email-desc">
We'll never share your email with anyone else.
</Description>
</TextField>
<TextField>
<Label>Password</Label>
<Input placeholder="Create a password" secureTextEntry />
<Description nativeID="password-desc">
Use at least 8 characters with a mix of letters, numbers, and symbols.
</Description>
</TextField>
</View>
);
}
```
更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/description.tsx>)。
## API 参考
### Description
| prop | type | default | description |
| --------------- | ----------------------------------- | ------- | ------------------------------------------------------------------------------------------ |
| `children` | `React.ReactNode` | - | 说明文本内容 |
| `className` | `string` | - | 额外 class |
| `nativeID` | `string` | - | 无障碍用 native ID，与 `aria-describedby` 等配合关联字段 |
| `isInvalid` | `boolean` | - | 是否处于非法态（可覆盖上下文） |
| `isDisabled` | `boolean` | - | 是否禁用态（可覆盖上下文） |
| `hideOnInvalid` | `boolean` | `false` | 非法时是否隐藏说明 |
| `animation` | `DescriptionAnimation \| undefined` | - | 说明显隐等过渡的动画配置 |
| `...TextProps` | `TextProps` | - | 支持 React Native `Text` 的全部标准属性 |
apps/docs/content/docs/cn/native/components/(forms)/field-error.mdx
+214
View File
@@ -0,0 +1,214 @@
---
title: FieldError 字段错误
description: 展示校验错误信息，并带有平滑动画。
links:
source_native: field-error/field-error.tsx
styles_native: field-error/field-error.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/field-error-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/field-error-docs-dark.mp4"
/>
## 导入
```tsx
import { FieldError } from 'heroui-native';
```
## 结构
```tsx
<FieldError>错误信息内容</FieldError>
```
- **FieldError**：展示错误信息的主容器，带动画。字符串子节点会自动用 `Text` 包裹，也可传入自定义 React 节点。通过 `isInvalid` 控制显隐，并支持自定义进入/退出动画。
## 用法
### 基础用法
校验失败时展示错误信息。
```tsx
<FieldError isInvalid={true}>此字段为必填</FieldError>
```
### 受控显隐
使用 `isInvalid` 控制何时显示。放在 `TextField` 等表单项内时，会自动消费 form-item-state 上下文。
```tsx
const [isInvalid, setIsInvalid] = useState(false);
<FieldError isInvalid={isInvalid}>请输入有效的邮箱地址</FieldError>;
```
### 与表单字段配合
`FieldError` 会通过 form-item-state 上下文自动读取 `TextField` 的表单状态。
```tsx
import { FieldError, Label, TextField } from 'heroui-native';
<TextField isRequired isInvalid={true}>
<Label>邮箱</Label>
<Input placeholder="请输入邮箱" />
<FieldError>请输入有效的邮箱地址</FieldError>
</TextField>
```
### 自定义内容
子节点可传入自定义 React 组件而非纯字符串。
```tsx
<FieldError isInvalid={true}>
<View className="flex-row items-center">
<Icon name="alert-circle" />
<Text className="ml-2 text-danger">输入无效</Text>
</View>
</FieldError>
```
### 自定义动画
使用 `animation` 覆盖默认进入/退出动画。
```tsx
import { SlideInDown, SlideOutUp } from 'react-native-reanimated';
<FieldError
isInvalid={true}
animation={{
entering: { value: SlideInDown.duration(200) },
exiting: { value: SlideOutUp.duration(150) },
}}
>
字段校验未通过
</FieldError>;
```
完全禁用动画：
```tsx
<FieldError isInvalid={true} animation={false}>
字段校验未通过
</FieldError>
```
### 自定义样式
为容器与文字应用自定义样式。
```tsx
<FieldError
isInvalid={true}
className="mt-2"
classNames={{
container: 'bg-danger/10 p-2 rounded',
text: 'text-xs font-medium',
}}
>
密码至少 8 位
</FieldError>
```
### 自定义 Text 属性
当子节点为字符串时，可通过 `textProps` 传给内部 `Text`。
```tsx
<FieldError
isInvalid={true}
textProps={{
numberOfLines: 1,
ellipsizeMode: 'tail',
style: { letterSpacing: 0.5 },
}}
>
这是一段可能很长需要截断的错误提示文案示例
</FieldError>
```
## 示例
```tsx
import { Description, FieldError, Label, TextField } from 'heroui-native';
import { useState } from 'react';
import { View } from 'react-native';
export default function FieldErrorExample() {
const [email, setEmail] = useState('');
const [isInvalid, setIsInvalid] = useState(false);
const isValidEmail = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
const handleBlur = () => {
setIsInvalid(email !== '' && !isValidEmail);
};
return (
<View className="p-4">
<TextField isInvalid={isInvalid}>
<Label>邮箱地址</Label>
<Input
placeholder="请输入邮箱"
value={email}
onChangeText={setEmail}
onBlur={handleBlur}
keyboardType="email-address"
autoCapitalize="none"
/>
<Description>
我们将通过此邮箱与您联系
</Description>
<FieldError>请输入有效的邮箱地址</FieldError>
</TextField>
</View>
);
}
```
更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/field-error.tsx)。
## API 参考
### FieldError
| prop | type | default | description |
| ---------------------- | --------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `children` | `React.ReactNode` | `undefined` | 错误内容；字符串子节点会用 `Text` 包裹 |
| `isInvalid` | `boolean` | `undefined` | 控制是否显示（可覆盖 form-item-state）。置于 `TextField` 内时会自动消费表单状态 |
| `animation` | `FieldErrorRootAnimation` | - | 动画配置 |
| `className` | `string` | `undefined` | 容器的额外 class |
| `classNames` | `ElementSlots<FieldErrorSlots>` | `undefined` | 各部分的额外 class |
| `styles` | `{ container?: ViewStyle; text?: TextStyle }` | `undefined` | 容器与文字的样式 |
| `textProps` | `TextProps` | `undefined` | 子节点为字符串时传给 `Text` 的额外属性 |
| `...AnimatedViewProps` | `AnimatedProps<ViewProps>` | - | 支持 Reanimated `Animated.View` 的全部属性 |
**classNames：** `ElementSlots<FieldErrorSlots>` 为各部分提供类型安全的 class。可用插槽：`container`、`text`。
#### `styles`
| prop | type | description |
| ----------- | ----------- | ----------- |
| `container` | `ViewStyle` | 容器样式 |
| `text` | `TextStyle` | 文字样式 |
#### FieldErrorRootAnimation
根组件动画配置，可为：
- `false` 或 `"disabled"`：仅禁用根级动画
- `"disable-all"`：禁用全部动画（含子级）
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| ---------------- | ---------------------------------------- | --------------------------------------------------------------------- | ------------------------ |
| `state` | `'disabled' \| 'disable-all' \| boolean` | - | 在自定义属性时禁用动画 |
| `entering.value` | `EntryOrExitLayoutType` | `FadeIn`<br/>`.duration(150)`<br/>`.easing(Easing.out(Easing.ease))` | 自定义进入动画 |
| `exiting.value` | `EntryOrExitLayoutType` | `FadeOut`<br/>`.duration(100)`<br/>`.easing(Easing.out(Easing.ease))` | 自定义退出动画 |
apps/docs/content/docs/cn/native/components/(forms)/input-group.mdx
+207
View File
@@ -0,0 +1,207 @@
---
title: InputGroup 输入框组
description: 复合布局组件，将输入框与可选的前后缀装饰组合在一起。
links:
source_native: input-group/input-group.tsx
styles_native: input-group/input-group.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-group-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-group-docs-dark.mp4"
/>
## 导入
```tsx
import { InputGroup } from 'heroui-native';
```
## 结构
```tsx
<InputGroup>
<InputGroup.Prefix>...</InputGroup.Prefix>
<InputGroup.Input />
<InputGroup.Suffix>...</InputGroup.Suffix>
</InputGroup>
```
- **InputGroup**：布局容器，包裹前缀、输入与后缀；提供动画设置与测量上下文，自动将前后缀宽度应用为 `Input` 的内边距。
- **InputGroup.Prefix**：绝对定位在输入左侧；测量宽度自动作为 `InputGroup.Input` 的 `paddingLeft`。
- **InputGroup.Suffix**：绝对定位在输入右侧；测量宽度自动作为 `InputGroup.Input` 的 `paddingRight`。
- **InputGroup.Input**：透传至 `Input`，支持全部 `Input` 属性，并自动获得前后缀对应的左右内边距。
## 用法
### 基础用法
通过复合子部件为输入框附加前后缀内容。
```tsx
<InputGroup>
<InputGroup.Prefix>...</InputGroup.Prefix>
<InputGroup.Input placeholder="请输入" />
<InputGroup.Suffix>...</InputGroup.Suffix>
</InputGroup>
```
### 仅前缀
在输入前附加图标等内容。
```tsx
<InputGroup>
<InputGroup.Prefix isDecorative>
<PersonIcon size={16} />
</InputGroup.Prefix>
<InputGroup.Input placeholder="用户名" />
</InputGroup>
```
### 仅后缀
在输入后附加图标等内容。
```tsx
<InputGroup>
<InputGroup.Input placeholder="搜索商品…" />
<InputGroup.Suffix isDecorative>
<MagnifierIcon size={16} />
</InputGroup.Suffix>
</InputGroup>
```
### 装饰性与可交互
在 `Prefix`/`Suffix` 上设置 `isDecorative` 时，触摸事件会穿透到 `Input`，且对读屏隐藏装饰内容；包含可交互元素时不要设置。
```tsx
<InputGroup>
<InputGroup.Prefix isDecorative>
<LockIcon size={16} />
</InputGroup.Prefix>
<InputGroup.Input placeholder="请输入密码" secureTextEntry />
<InputGroup.Suffix>
<Pressable onPress={togglePasswordVisibility}>
<EyeIcon size={16} />
</Pressable>
</InputGroup.Suffix>
</InputGroup>
```
### 禁用状态
禁用整个输入组，状态会级联到子组件。
```tsx
<InputGroup isDisabled>
<InputGroup.Prefix isDecorative>
<LockIcon size={16} />
</InputGroup.Prefix>
<InputGroup.Input placeholder="已禁用" />
</InputGroup>
```
### 与 TextField 组合
与 `TextField`、`Label`、`Description` 等组合成完整表单项。
```tsx
<TextField isRequired>
<Label>邮箱</Label>
<InputGroup>
<InputGroup.Prefix isDecorative>
<MailIcon size={16} />
</InputGroup.Prefix>
<InputGroup.Input placeholder="you@example.com" keyboardType="email-address" />
</InputGroup>
<Description>我们不会公开您的邮箱</Description>
</TextField>
```
## 示例
```tsx
import { InputGroup } from 'heroui-native';
import { Ionicons } from '@expo/vector-icons';
import { useState } from 'react';
import { Pressable, View } from 'react-native';
export default function InputGroupExample() {
const [value, setValue] = useState('');
const [isPasswordVisible, setIsPasswordVisible] = useState(false);
return (
<View className="px-5">
<InputGroup>
<InputGroup.Prefix isDecorative>
<Ionicons name="lock-closed-outline" size={16} color="#888" />
</InputGroup.Prefix>
<InputGroup.Input
value={value}
onChangeText={setValue}
placeholder="请输入密码"
secureTextEntry={!isPasswordVisible}
/>
<InputGroup.Suffix>
<Pressable
onPress={() => setIsPasswordVisible(!isPasswordVisible)}
hitSlop={20}
>
<Ionicons
name={isPasswordVisible ? 'eye-off-outline' : 'eye-outline'}
size={16}
color="#888"
/>
</Pressable>
</InputGroup.Suffix>
</InputGroup>
</View>
);
}
```
更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/input-group.tsx>)。
## API 参考
### InputGroup
| prop | type | default | description |
| -------------- | ------------------------ | ------- | ---------------------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 组内子节点 |
| `className` | `string` | - | 额外的 class |
| `isDisabled` | `boolean` | `false` | 是否禁用整个输入组及子级 |
| `animation` | `AnimationRootDisableAll`| - | 输入组动画配置 |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部属性 |
#### AnimationRootDisableAll
根组件动画配置，可为：
- `"disable-all"`：禁用全部动画（含子级，级联）
- `undefined`：使用默认动画
### InputGroup.Prefix
| prop | type | default | description |
| ---------------- | ----------------- | ------- | -------------------------------------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 前缀区域内容 |
| `className` | `string` | - | 额外的 class |
| `isDecorative` | `boolean` | `false` | 为 true 时触摸穿透到 `Input`，且对读屏隐藏 |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部属性 |
### InputGroup.Suffix
| prop | type | default | description |
| ---------------- | ----------------- | ------- | -------------------------------------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 后缀区域内容 |
| `className` | `string` | - | 额外的 class |
| `isDecorative` | `boolean` | `false` | 为 true 时触摸穿透到 `Input`，且对读屏隐藏 |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部属性 |
### InputGroup.Input
透传至 [Input](./input) 组件，支持其全部属性。
apps/docs/content/docs/cn/native/components/(forms)/input-otp.mdx
+415
View File
@@ -0,0 +1,415 @@
---
title: InputOTP 一次性密码输入框
description: 用于输入一次性验证码（OTP）的输入组件，支持分格、动画与校验。
links:
source_native: input-otp/input-otp.tsx
styles_native: input-otp/input-otp.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-otp-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-otp-docs-dark.mp4"
/>
## 导入
```tsx
import { InputOTP } from 'heroui-native';
```
## 结构
```tsx
<InputOTP>
<InputOTP.Group>
<InputOTP.Slot index={0} />
<InputOTP.Slot index={1} />
</InputOTP.Group>
<InputOTP.Separator />
<InputOTP.Group>
<InputOTP.Slot index={2}>
<InputOTP.SlotPlaceholder />
<InputOTP.SlotValue />
<InputOTP.SlotCaret />
</InputOTP.Slot>
</InputOTP.Group>
</InputOTP>
```
- **InputOTP**：根容器，管理 OTP 状态与文本变更，并为子组件提供上下文；处理焦点、校验与字符输入。
- **InputOTP.Group**：将多个格子编组；用于视觉分组（例如每 3 位一组）。
- **InputOTP.Slot**：单个字符格；`index` 须在 OTP 序列中唯一且与位置对应。未提供子节点时，默认渲染 `SlotPlaceholder`、`SlotValue` 与 `SlotCaret`。
- **InputOTP.SlotPlaceholder**：空位时显示的占位字符；`Slot` 无子节点时默认使用。
- **InputOTP.SlotValue**：显示已输入字符并带动画；`Slot` 无子节点时默认使用。
- **InputOTP.SlotCaret**：动画光标，指示当前输入位置；置于 `Slot` 内以显示正在输入的位置。
- **InputOTP.Separator**：分组之间的视觉分隔符。
## 用法
### 基础用法
创建 6 位 OTP，分两组并带分隔符。
```tsx
<InputOTP maxLength={6} onComplete={(code) => console.log(code)}>
<InputOTP.Group>
<InputOTP.Slot index={0} />
<InputOTP.Slot index={1} />
<InputOTP.Slot index={2} />
</InputOTP.Group>
<InputOTP.Separator />
<InputOTP.Group>
<InputOTP.Slot index={3} />
<InputOTP.Slot index={4} />
<InputOTP.Slot index={5} />
</InputOTP.Group>
</InputOTP>
```
### 四位 PIN
简单的 4 位数字 PIN。
```tsx
<InputOTP maxLength={4} onComplete={(code) => console.log(code)}>
<InputOTP.Slot index={0} />
<InputOTP.Slot index={1} />
<InputOTP.Slot index={2} />
<InputOTP.Slot index={3} />
</InputOTP>
```
### 自定义占位
为每个格子位置提供自定义占位字符。
```tsx
<InputOTP
maxLength={6}
placeholder="——————"
onComplete={(code) => console.log(code)}
>
<InputOTP.Group>
{({ slots }) => (
<>
{slots.map((slot) => (
<InputOTP.Slot key={slot.index} index={slot.index} />
))}
</>
)}
</InputOTP.Group>
</InputOTP>
```
### 受控值
以编程方式控制 OTP 值。
```tsx
const [value, setValue] = useState('');
<InputOTP value={value} onChange={setValue} maxLength={6}>
<InputOTP.Group>
<InputOTP.Slot index={0} />
<InputOTP.Slot index={1} />
<InputOTP.Slot index={2} />
</InputOTP.Group>
<InputOTP.Separator />
<InputOTP.Group>
<InputOTP.Slot index={3} />
<InputOTP.Slot index={4} />
<InputOTP.Slot index={5} />
</InputOTP.Group>
</InputOTP>;
```
### 校验态
非法时展示校验错误样式。
```tsx
<InputOTP value={value} onChange={setValue} maxLength={6} isInvalid={isInvalid}>
<InputOTP.Group>
<InputOTP.Slot index={0} />
<InputOTP.Slot index={1} />
<InputOTP.Slot index={2} />
</InputOTP.Group>
<InputOTP.Separator />
<InputOTP.Group>
<InputOTP.Slot index={3} />
<InputOTP.Slot index={4} />
<InputOTP.Slot index={5} />
</InputOTP.Group>
</InputOTP>
```
### 输入模式（正则）
使用正则限制可输入字符。内置：`REGEXP_ONLY_DIGITS`（0–9）、`REGEXP_ONLY_CHARS`（a–z、A–Z）、`REGEXP_ONLY_DIGITS_AND_CHARS`（数字与字母）。
```tsx
import { InputOTP, REGEXP_ONLY_CHARS } from 'heroui-native';
<InputOTP
maxLength={6}
pattern={REGEXP_ONLY_CHARS}
inputMode="text"
onComplete={(code) => console.log(code)}
>
<InputOTP.Group>
<InputOTP.Slot index={0} />
<InputOTP.Slot index={1} />
<InputOTP.Slot index={2} />
</InputOTP.Group>
<InputOTP.Separator />
<InputOTP.Group>
<InputOTP.Slot index={3} />
<InputOTP.Slot index={4} />
<InputOTP.Slot index={5} />
</InputOTP.Group>
</InputOTP>;
```
### 自定义布局
在 `Group` 上使用渲染属性以自定义格子布局。
```tsx
<InputOTP maxLength={6}>
<InputOTP.Group>
{({ slots, isFocused, isInvalid }) => (
<>
{slots.map((slot) => (
<InputOTP.Slot
key={slot.index}
index={slot.index}
className={cn('custom-class', slot.isActive && 'active-class')}
>
<InputOTP.SlotPlaceholder />
<InputOTP.SlotValue />
<InputOTP.SlotCaret />
</InputOTP.Slot>
))}
</>
)}
</InputOTP.Group>
</InputOTP>
```
### 在底部抽屉内
在 `BottomSheet` 中渲染 `InputOTP` 时，使用 `useBottomSheetAwareHandlers` 返回的 `onFocus` / `onBlur` 传给 `InputOTP`，以正确处理键盘避让。
```tsx
import { InputOTP, useBottomSheetAwareHandlers } from 'heroui-native';
const BottomSheetOTPInput = () => {
const { onFocus, onBlur } = useBottomSheetAwareHandlers();
return (
<InputOTP maxLength={6} onFocus={onFocus} onBlur={onBlur}>
<InputOTP.Group>
<InputOTP.Slot index={0} />
<InputOTP.Slot index={1} />
<InputOTP.Slot index={2} />
</InputOTP.Group>
<InputOTP.Separator />
<InputOTP.Group>
<InputOTP.Slot index={3} />
<InputOTP.Slot index={4} />
<InputOTP.Slot index={5} />
</InputOTP.Group>
</InputOTP>
);
};
```
## 示例
```tsx
import { InputOTP, Label, Description, type InputOTPRef } from 'heroui-native';
import { View } from 'react-native';
import { useRef } from 'react';
export default function InputOTPExample() {
const ref = useRef<InputOTPRef>(null);
const onComplete = (code: string) => {
console.log('OTP completed:', code);
setTimeout(() => {
ref.current?.clear();
}, 1000);
};
return (
<View className="flex-1 px-5 items-center justify-center">
<View>
<Label>验证账户</Label>
<Description className="mb-3">
我们已向 a****@gmail.com 发送验证码
</Description>
<InputOTP ref={ref} maxLength={6} onComplete={onComplete}>
<InputOTP.Group>
<InputOTP.Slot index={0} />
<InputOTP.Slot index={1} />
<InputOTP.Slot index={2} />
</InputOTP.Group>
<InputOTP.Separator />
<InputOTP.Group>
<InputOTP.Slot index={3} />
<InputOTP.Slot index={4} />
<InputOTP.Slot index={5} />
</InputOTP.Group>
</InputOTP>
</View>
</View>
);
}
```
更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/input-otp.tsx)。
## API 参考
### InputOTP
| prop | type | default | description |
| -------------------------- | ----------------------------- | ----------- | ------------------------------------------------------------------------------------------ |
| `maxLength` | `number` | - | OTP 最大长度（必填） |
| `value` | `string` | - | 受控值 |
| `defaultValue` | `string` | - | 非受控默认值 |
| `onChange` | `(value: string) => void` | - | 值变化回调 |
| `onComplete` | `(value: string) => void` | - | 所有格子填满时触发 |
| `isDisabled` | `boolean` | `false` | 是否禁用 |
| `isInvalid` | `boolean` | `false` | 是否处于非法状态 |
| `pattern` | `string` | - | 允许字符的正则（如 `REGEXP_ONLY_DIGITS`、`REGEXP_ONLY_CHARS`） |
| `inputMode` | `TextInputProps['inputMode']` | `'numeric'` | 输入模式 |
| `placeholder` | `string` | - | 占位字符串；每个字符对应一个格子位置 |
| `placeholderTextColor` | `string` | - | 全部格子的占位文字颜色 |
| `placeholderTextClassName` | `string` | - | 全部格子的占位文字 class |
| `pasteTransformer` | `(text: string) => string` | - | 粘贴内容转换（如去掉连字符）；默认会移除非匹配字符 |
| `onFocus` | `(e: FocusEvent) => void` | - | 聚焦回调 |
| `onBlur` | `(e: BlurEvent) => void` | - | 失焦回调 |
| `textInputProps` | `Omit<TextInputProps, ...>` | - | 透传给底层 `TextInput` 的额外属性 |
| `children` | `React.ReactNode` | - | 子节点 |
| `className` | `string` | - | 根容器额外 class |
| `style` | `PressableProps['style']` | - | 传给容器 `Pressable` 的样式 |
| `isBottomSheetAware` | `boolean` | `true` | 在 `BottomSheet` 内是否自动处理键盘相关状态；设为 `false` 可关闭 |
| `animation` | `"disable-all" \| undefined` | `undefined` | 动画配置；`"disable-all"` 可禁用自身及子级全部动画 |
### InputOTP.Group
| prop | type | default | description |
| -------------- | --------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `children` | `React.ReactNode \| ((props: InputOTPGroupRenderProps) => React.ReactNode)` | - | 子节点，或接收格子数据与上下文的渲染函数 |
| `className` | `string` | - | 额外 class |
| `...ViewProps` | `ViewProps` | - | 支持全部标准 React Native `View` 属性 |
#### InputOTPGroupRenderProps
| prop | type | description |
| ------------ | ------------ | ---------------------------------------- |
| `slots` | `SlotData[]` | 每个位置的格子数据数组 |
| `maxLength` | `number` | OTP 最大长度 |
| `value` | `string` | 当前 OTP 值 |
| `isFocused` | `boolean` | 是否聚焦 |
| `isDisabled` | `boolean` | 是否禁用 |
| `isInvalid` | `boolean` | 是否非法 |
### InputOTP.Slot
| prop | type | default | description |
| -------------- | ----------------- | ------- | ------------------------------------------------------------------------------------------- |
| `index` | `number` | - | 格子下标（必填），须为 `0` 到 `maxLength - 1` |
| `children` | `React.ReactNode` | - | 自定义格子内容；未提供时默认为 `SlotPlaceholder`、`SlotValue`、`SlotCaret` |
| `className` | `string` | - | 额外 class |
| `style` | `ViewStyle` | - | 额外样式 |
| `...ViewProps` | `ViewProps` | - | 支持全部标准 React Native `View` 属性 |
### InputOTP.SlotPlaceholder
| prop | type | default | description |
| -------------- | ----------- | ------- | -------------------------------------------------------------------- |
| `children` | `string` | - | 显示文本（可选，默认使用 `slot.placeholderChar`） |
| `className` | `string` | - | 额外 class |
| `style` | `TextStyle` | - | 额外样式 |
| `...TextProps` | `TextProps` | - | 支持全部标准 React Native `Text` 属性 |
### InputOTP.SlotValue
| prop | type | default | description |
| -------------- | ---------------------------- | ------- | --------------------------------------------------------- |
| `children` | `string` | - | 显示文本（可选，默认使用 `slot.char`） |
| `className` | `string` | - | 额外 class |
| `animation` | `InputOTPSlotValueAnimation` | - | `SlotValue` 动画配置 |
| `...TextProps` | `TextProps` | - | 支持全部标准 React Native `Text` 属性 |
#### InputOTPSlotValueAnimation
`InputOTP.SlotValue` 动画配置，可为：
- `false` 或 `"disabled"`：禁用全部动画
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| ------------------ | ----------------------- | ---------------------------------------- | ----------------------------------------------- |
| `state` | `'disabled' \| boolean` | - | 在自定义属性时用于禁用动画 |
| `wrapper.entering` | `EntryOrExitLayoutType` | `FadeIn.duration(250)` | 包裹层进入动画 |
| `wrapper.exiting` | `EntryOrExitLayoutType` | `FadeOut.duration(100)` | 包裹层退出动画 |
| `text.entering` | `EntryOrExitLayoutType` | `FlipInXDown.duration(250).easing(...)` | 文本进入动画 |
| `text.exiting` | `EntryOrExitLayoutType` | `FlipOutXDown.duration(250).easing(...)` | 文本退出动画 |
### InputOTP.SlotCaret
| prop | type | default | description |
| ----------------------- | ---------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `className` | `string` | - | 额外 class |
| `style` | `ViewStyle` | - | 额外样式 |
| `animation` | `InputOTPSlotCaretAnimation` | - | `SlotCaret` 动画配置 |
| `isAnimatedStyleActive` | `boolean` | `true` | 是否启用 Reanimated 动画样式；为 `false` 时移除内置动画样式，可自行实现 |
| `pointerEvents` | `'none' \| 'auto' \| ...` | `'none'` | 指针事件配置 |
| `...ViewProps` | `ViewProps` | - | 支持全部标准 React Native `View` 属性 |
#### InputOTPSlotCaretAnimation
`InputOTP.SlotCaret` 动画配置，可为：
- `false` 或 `"disabled"`：禁用全部动画
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| ------------------ | ----------------------- | ---------- | ----------------------------------------------- |
| `state` | `'disabled' \| boolean` | - | 在自定义属性时用于禁用动画 |
| `opacity.value` | `[number, number]` | `[0, 1]` | 透明度 [最小, 最大] |
| `opacity.duration` | `number` | `500` | 动画时长（毫秒） |
| `height.value` | `[number, number]` | `[16, 18]` | 高度 [最小, 最大]（像素） |
| `height.duration` | `number` | `500` | 动画时长（毫秒） |
### InputOTP.Separator
| prop | type | default | description |
| -------------- | ----------- | ------- | -------------------------------------------------- |
| `className` | `string` | - | 额外 class |
| `...ViewProps` | `ViewProps` | - | 支持全部标准 React Native `View` 属性 |
## Hooks
### useInputOTP
读取 `InputOTP` 根上下文，须在 `InputOTP` 内使用。
```tsx
const { value, maxLength, isFocused, isDisabled, isInvalid, slots } =
useInputOTP();
```
### useInputOTPSlot
读取 `InputOTP.Slot` 上下文，须在 `InputOTP.Slot` 内使用。
```tsx
const { slot, isActive, isCaretVisible } = useInputOTPSlot();
```
apps/docs/content/docs/cn/native/components/(forms)/input.mdx
+226
View File
@@ -0,0 +1,226 @@
---
title: Input 输入框
description: 单行文本输入，带样式边框与背景，用于收集用户输入。
links:
source_native: input/input.tsx
styles_native: input/input.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-docs-dark.mp4"
/>
## 导入
```tsx
import { Input } from 'heroui-native';
```
## 用法
### 基础用法
`Input` 可单独使用，也可放在 `TextField` 内。
```tsx
import { Input } from 'heroui-native';
<Input placeholder="请输入邮箱" />;
```
### 与 TextField 组合
与 `TextField` 搭配形成完整表单结构。
```tsx
import { Input, Label, TextField } from 'heroui-native';
<TextField>
<Label>邮箱</Label>
<Input placeholder="请输入邮箱" />
</TextField>;
```
### 校验状态
非法时展示错误样式。
```tsx
import { FieldError, Input, Label, TextField } from 'heroui-native';
<TextField isRequired isInvalid={true}>
<Label>邮箱</Label>
<Input placeholder="请输入邮箱" />
<FieldError>请输入有效邮箱</FieldError>
</TextField>;
```
### 局部覆盖非法状态
在输入上覆盖上下文中的非法状态。
```tsx
import { FieldError, Input, Label, TextField } from 'heroui-native';
<TextField isInvalid={true}>
<Label isInvalid={false}>邮箱</Label>
<Input placeholder="请输入邮箱" isInvalid={false} />
<FieldError>邮箱格式不正确</FieldError>
</TextField>;
```
### 禁用状态
禁用输入，阻止交互。
```tsx
import { Input, Label, TextField } from 'heroui-native';
<TextField isDisabled>
<Label>禁用字段</Label>
<Input placeholder="不可编辑" value="只读内容" />
</TextField>;
```
### 变体
按场景使用不同视觉变体。
```tsx
import { Input, Label, TextField } from 'heroui-native';
<TextField>
<Label>主要变体</Label>
<Input placeholder="主要样式" variant="primary" />
</TextField>
<TextField>
<Label>次要变体</Label>
<Input placeholder="次要样式" variant="secondary" />
</TextField>
```
### 自定义样式
通过 `className` 自定义外观。
```tsx
import { Input, Label, TextField } from 'heroui-native';
<TextField>
<Label>自定义样式</Label>
<Input
placeholder="自定义颜色"
className="bg-blue-50 border-blue-500 focus:border-blue-700"
/>
</TextField>;
```
### 在 Bottom Sheet 内
在 `BottomSheet` 中渲染 `Input` 时，使用 `useBottomSheetAwareHandlers` 连接键盘避让：将返回的 `onFocus`、`onBlur` 传给 `Input`。
```tsx
import { Input, TextField, useBottomSheetAwareHandlers } from 'heroui-native';
const BottomSheetTextInput = () => {
const { onFocus, onBlur } = useBottomSheetAwareHandlers();
return (
<TextField>
<Input
placeholder="在此输入…"
onFocus={onFocus}
onBlur={onBlur}
/>
</TextField>
);
};
```
## 示例
```tsx
import { Ionicons } from '@expo/vector-icons';
import { Description, Input, Label, TextField } from 'heroui-native';
import { useState } from 'react';
import { Pressable, View } from 'react-native';
import { withUniwind } from 'uniwind';
const StyledIonicons = withUniwind(Ionicons);
export const TextInputContent = () => {
const [email, setEmail] = useState('');
const [password, setPassword] = useState('');
const [isPasswordVisible, setIsPasswordVisible] = useState(false);
return (
<View className="gap-4">
<TextField isRequired>
<Label>邮箱</Label>
<Input
placeholder="请输入邮箱"
keyboardType="email-address"
autoCapitalize="none"
value={email}
onChangeText={setEmail}
/>
<Description>
我们不会向他人公开您的邮箱。
</Description>
</TextField>
<TextField isRequired>
<Label>新密码</Label>
<View className="w-full flex-row items-center">
<Input
value={password}
onChangeText={setPassword}
className="flex-1 px-10"
placeholder="请输入密码"
secureTextEntry={!isPasswordVisible}
/>
<StyledIonicons
name="lock-closed-outline"
size={16}
className="absolute left-3.5 text-muted"
pointerEvents="none"
/>
<Pressable
className="absolute right-4"
onPress={() => setIsPasswordVisible(!isPasswordVisible)}
>
<StyledIonicons
name={isPasswordVisible ? 'eye-off-outline' : 'eye-outline'}
size={16}
className="text-muted"
/>
</Pressable>
</View>
<Description>密码至少 6 位</Description>
</TextField>
</View>
);
};
```
更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/input.tsx)。
## API 参考
### Input
| prop | type | default | description |
| ------------------------- | -------------------------- | --------------------- | ------------------------------------------------------------ |
| isInvalid | `boolean` | `undefined` | 是否非法（可覆盖上下文） |
| variant | `'primary' \| 'secondary'` | `'primary'` | 输入框视觉变体 |
| className | `string` | - | 自定义 class |
| selectionColorClassName | `string` | `"accent-accent"` | 选中文本颜色的 class |
| placeholderColorClassName | `string` | `"field-placeholder"` | 占位符文字颜色的 class |
| isBottomSheetAware | `boolean` | `true` | 在 BottomSheet 内是否自动处理键盘相关逻辑；设为 `false` 可关闭 |
| animation | `AnimationRoot` | `undefined` | 输入框动画配置 |
| ...TextInputProps | `TextInputProps` | - | 支持 React Native `TextInput` 的全部属性 |
> **说明**：置于 `TextField` 内时，`Input` 会通过 form-item-state 上下文自动消费 `isDisabled`、`isInvalid` 等表单状态。
apps/docs/content/docs/cn/native/components/(forms)/label.mdx
+197
View File
@@ -0,0 +1,197 @@
---
title: Label 标签
description: 用于标注表单字段等 UI 的文本组件，支持必填标记与校验状态。
links:
source_native: label/label.tsx
styles_native: label/label.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/label-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/label-docs-dark.mp4"
/>
## 导入
```tsx
import { Label } from 'heroui-native';
```
## 结构
```tsx
<Label>
<Label.Text>...</Label.Text>
</Label>
```
- **Label**：根容器，管理标签状态并为子组件提供上下文。传入字符串子节点时会自动渲染为 `Label.Text`。支持禁用、必填与非法状态。
- **Label.Text**：标签文字；在必填时自动显示星号，非法或禁用时改变颜色。
## 用法
### 基础用法
展示标签文字。字符串子节点会自动渲染为 `Label.Text`。
```tsx
<Label>用户名</Label>
```
### 与表单字段配合
将 `Label` 与表单字段组合以提供无障碍标签。
```tsx
<TextField>
<Label>用户名</Label>
<Input placeholder="请输入用户名" />
</TextField>
```
### 必填字段
使用 `isRequired` 显示必填星号。
```tsx
<TextField>
<Label isRequired>密码</Label>
<Input placeholder="创建密码" secureTextEntry />
</TextField>
```
### 非法状态
在校验失败时使用非法样式突出标签。
```tsx
import { FieldError, Label, TextField } from 'heroui-native';
<TextField isInvalid>
<Label isInvalid>确认密码</Label>
<Input
placeholder="再次输入密码"
secureTextEntry
value="different"
editable={false}
/>
<FieldError>两次密码不一致</FieldError>
</TextField>
```
### 禁用状态
禁用标签以表示字段不可交互。
```tsx
<TextField isDisabled>
<Label>订阅方案</Label>
<Input value="Premium" />
</TextField>
```
### 自定义布局
使用复合子组件自定义标签结构。
```tsx
<Label>
<Label.Text>自定义标签</Label.Text>
</Label>
```
### 自定义样式
通过 `className`、`classNames` 或 `styles` 传入样式。
```tsx
<Label className="mb-2">
<Label.Text
className="text-lg"
classNames={{
text: "font-bold",
asterisk: "text-danger"
}}
>
自定义样式标签
</Label.Text>
</Label>
```
## 示例
```tsx
import { FieldError, Label, TextField } from 'heroui-native';
import { View } from 'react-native';
export default function LabelExample() {
return (
<View className="flex-1 justify-center px-5 gap-8">
<TextField>
<Label>用户名</Label>
<Input placeholder="请输入用户名" />
</TextField>
<TextField>
<Label isRequired>密码</Label>
<Input placeholder="创建密码" secureTextEntry />
</TextField>
<TextField isInvalid>
<Label isInvalid>确认密码</Label>
<Input
placeholder="再次输入密码"
secureTextEntry
value="different"
editable={false}
/>
<FieldError>两次密码不一致</FieldError>
</TextField>
<TextField isDisabled>
<Label>订阅方案</Label>
<Input value="Premium" />
</TextField>
</View>
);
}
```
更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/label.tsx)。
## API 参考
### Label
| prop | type | default | description |
| ------------------- | ---------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 标签内容。为字符串时自动渲染为 `Label.Text`；否则按原样渲染子节点 |
| `isRequired` | `boolean` | `false` | 是否必填；为 true 时显示星号 |
| `isInvalid` | `boolean` | `false` | 是否非法；为 true 时文字使用危险色 |
| `isDisabled` | `boolean` | `false` | 是否禁用；应用禁用样式并阻止交互 |
| `className` | `string` | - | 额外的 class |
| `animation` | `"disable-all" \| undefined` | `undefined` | 动画配置；`"disable-all"` 可禁用自身及子级的全部动画 |
| `...PressableProps` | `PressableProps` | - | 支持 React Native `Pressable` 的全部属性 |
### Label.Text
| prop | type | default | description |
| -------------- | ---------------------------------------- | ------- | ---------------------------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 标签文字内容 |
| `className` | `string` | - | 文本元素的额外 class |
| `classNames` | `ElementSlots<LabelSlots>` | - | 标签各部分的额外 class |
| `styles` | `Partial<Record<LabelSlots, TextStyle>>` | - | 标签各部分的样式 |
| `nativeID` | `string` | - | 无障碍用原生 ID，通过 aria-labelledby 关联表单控件 |
| `...TextProps` | `TextProps` | - | 支持 React Native `Text` 的全部属性 |
#### `ElementSlots<LabelSlots>`
| prop | type | description |
| ---------- | -------- | ------------------ |
| `text` | `string` | 标签文字的 class |
| `asterisk` | `string` | 星号的 class |
#### `styles`
| prop | type | description |
| ---------- | ----------- | ----------- |
| `text` | `TextStyle` | 标签文字样式 |
| `asterisk` | `TextStyle` | 星号样式 |
apps/docs/content/docs/cn/native/components/(forms)/radio-group.mdx
+339
View File
@@ -0,0 +1,339 @@
---
title: RadioGroup 单选框组
description: 单选按钮组，同一时间只能选中一个选项。
links:
source_native: radio-group/radio-group.tsx
styles_native: radio-group/radio-group.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/radio-group-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/radio-group-docs-dark.mp4"
/>
## 导入
```tsx
import { RadioGroup } from 'heroui-native';
```
## 结构
```tsx
<RadioGroup>
<RadioGroup.Item>
<Label>...</Label>
<Description>...</Description>
<Radio>
<Radio.Indicator>
<Radio.IndicatorThumb />
</Radio.Indicator>
</Radio>
</RadioGroup.Item>
<FieldError>...</FieldError>
</RadioGroup>
```
- **RadioGroup**：管理单选项选中状态的容器，支持横向与纵向布局。
- **RadioGroup.Item**：组内单个选项，必须放在 `RadioGroup` 内。处理选中状态；在仅提供文本子节点时会渲染默认 `<Radio />` 指示器。支持渲染函数子节点以访问状态（`isSelected`、`isInvalid`、`isDisabled`）。
- **Label**：可选的可点击文字标签，与单选项关联以提升无障碍。请直接使用 [Label](./label) 组件。
- **Description**：标签下方的可选说明文字。请直接使用 [Description](./description) 组件。
- **Radio**：置于 `RadioGroup.Item` 内的 [Radio](./radio) 组件，用于渲染单选指示器。会自动识别 `RadioGroupItem` 上下文并从中获取 `isSelected`、`isDisabled`、`isInvalid` 与 `variant`。
- **Radio.Indicator**：单选圆环的可选容器；无子节点时渲染默认拇指样式，管理选中视觉。完整 API 见 [Radio](./radio)。
- **Radio.IndicatorThumb**：选中时显示的可选内圆，随选中状态缩放动画；可替换为自定义内容。见 [Radio](./radio)。
- **FieldError**：在组无效时显示的错误信息，带动画显示在组内容下方。请直接使用 [FieldError](./field-error) 组件。
## 用法
### 基础用法
使用简单字符串子节点时，会自动渲染标题与指示器。
```tsx
<RadioGroup value={value} onValueChange={setValue}>
<RadioGroup.Item value="option1">选项 1</RadioGroup.Item>
<RadioGroup.Item value="option2">选项 2</RadioGroup.Item>
<RadioGroup.Item value="option3">选项 3</RadioGroup.Item>
</RadioGroup>
```
### 带说明文字
在每个选项下方添加描述以补充上下文。
```tsx
import { RadioGroup, Radio, Label, Description } from 'heroui-native';
import { View } from 'react-native';
<RadioGroup value={value} onValueChange={setValue}>
<RadioGroup.Item value="standard">
<View>
<Label>标准配送</Label>
<Description>5–7 个工作日送达</Description>
</View>
<Radio />
</RadioGroup.Item>
<RadioGroup.Item value="express">
<View>
<Label>加急配送</Label>
<Description>2–3 个工作日送达</Description>
</View>
<Radio />
</RadioGroup.Item>
</RadioGroup>;
```
### 自定义指示器
使用 `Radio` 子组件将默认拇指替换为自定义内容。
```tsx
import { RadioGroup, Radio, Label } from 'heroui-native';
<RadioGroup value={value} onValueChange={setValue}>
<RadioGroup.Item value="custom">
{({ isSelected }) => (
<>
<Label>自定义选项</Label>
<Radio>
<Radio.Indicator>
{isSelected && (
<Animated.View entering={FadeIn}>
<Icon name="check" size={12} />
</Animated.View>
)}
</Radio.Indicator>
</Radio>
</>
)}
</RadioGroup.Item>
</RadioGroup>;
```
### 使用渲染函数
在 `RadioGroup.Item` 上使用渲染函数以访问状态并自定义整块内容。
```tsx
import { RadioGroup, Radio, Label } from 'heroui-native';
<RadioGroup value={value} onValueChange={setValue}>
<RadioGroup.Item value="option1">
{({ isSelected, isInvalid, isDisabled }) => (
<>
<Label>选项 1</Label>
<Radio>
<Radio.Indicator>{isSelected && <CustomIcon />}</Radio.Indicator>
</Radio>
</>
)}
</RadioGroup.Item>
</RadioGroup>;
```
### 显示错误信息
在单选组下方展示校验错误。
```tsx
import { RadioGroup, FieldError } from 'heroui-native';
function RadioGroupWithError() {
const [value, setValue] = React.useState<string | undefined>(undefined);
return (
<RadioGroup value={value} onValueChange={setValue} isInvalid={!value}>
<RadioGroup.Item value="agree">我同意条款</RadioGroup.Item>
<RadioGroup.Item value="disagree">我不同意</RadioGroup.Item>
<FieldError isInvalid={!value}>
请选择一项以继续
</FieldError>
</RadioGroup>
);
}
```
## 示例
```tsx
import {
Description,
Label,
Radio,
RadioGroup,
Separator,
Surface,
} from 'heroui-native';
import React from 'react';
import { View } from 'react-native';
export default function RadioGroupExample() {
const [selection, setSelection] = React.useState('desc1');
return (
<Surface className="w-full">
<RadioGroup value={selection} onValueChange={setSelection}>
<RadioGroup.Item value="desc1">
<View>
<Label>标准配送</Label>
<Description>5–7 个工作日送达</Description>
</View>
<Radio />
</RadioGroup.Item>
<Separator className="my-1" />
<RadioGroup.Item value="desc2">
<View>
<Label>加急配送</Label>
<Description>2–3 个工作日送达</Description>
</View>
<Radio />
</RadioGroup.Item>
<Separator className="my-1" />
<RadioGroup.Item value="desc3">
<View>
<Label>次日达</Label>
<Description>下一个工作日送达</Description>
</View>
<Radio />
</RadioGroup.Item>
</RadioGroup>
</Surface>
);
}
```
更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/radio-group.tsx>)。
## API 参考
### RadioGroup
| prop | type | default | description |
| --------------- | ---------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
| `children` | `React.ReactNode` | `undefined` | 单选组内容 |
| `value` | `string \| undefined` | `undefined` | 当前选中值 |
| `onValueChange` | `(val: string) => void` | `undefined` | 选中值变化时的回调 |
| `isDisabled` | `boolean` | `false` | 是否禁用整个单选组 |
| `isInvalid` | `boolean` | `false` | 组是否处于无效状态 |
| `variant` | `'primary' \| 'secondary'` | `undefined` | 单选组样式变体（子项未单独设置时继承） |
| `animation` | `"disable-all" \| undefined` | `undefined` | 动画配置。使用 `"disable-all"` 可关闭包含子节点在内的全部动画 |
| `className` | `string` | `undefined` | 自定义 className |
| `...ViewProps` | `ViewProps` | - | 支持全部标准 React Native View 属性 |
### RadioGroup.Item
| prop | type | default | description |
| ------------------- | ---------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------- |
| `children` | `React.ReactNode \| ((props: RadioGroupItemRenderProps) => React.ReactNode)` | `undefined` | 选项内容，或用于自定义项的渲染函数 |
| `value` | `string` | `undefined` | 该选项关联的值 |
| `isDisabled` | `boolean` | `false` | 是否禁用该选项 |
| `isInvalid` | `boolean` | `false` | 该选项是否无效 |
| `variant` | `'primary' \| 'secondary'` | `'primary'` | 该选项的样式变体 |
| `hitSlop` | `number` | `6` | 可点击区域的热区扩展 |
| `className` | `string` | `undefined` | 自定义 className |
| `...PressableProps` | `PressableProps` | - | 支持全部标准 Pressable 属性（不含 disabled） |
#### RadioGroupItemRenderProps
| prop | type | description |
| ------------ | --------- | ---------------------------------- |
| `isSelected` | `boolean` | 该选项是否选中 |
| `isInvalid` | `boolean` | 该选项是否无效 |
| `isDisabled` | `boolean` | 该选项是否禁用 |
### Radio（位于 RadioGroup.Item 内）
`Radio` 放在 `RadioGroup.Item` 内用于渲染单选指示器。此时会自动识别 `RadioGroupItem` 上下文并从中获取 `isSelected`、`isDisabled`、`isInvalid` 与 `variant`，无需手动传参。
使用 `<Radio />` 获得默认指示器，或组合 `Radio.Indicator` 与 `Radio.IndicatorThumb` 自定义样式。
| prop | type | default | description |
| ------------------- | ------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------- |
| `children` | `React.ReactNode \| ((props: RadioRenderProps) => React.ReactNode)` | `undefined` | 子元素或渲染函数以自定义单选 |
| `variant` | `'primary' \| 'secondary'` | `'primary'` | 单选视觉变体 |
| `isSelected` | `boolean` | `undefined` | 是否选中 |
| `isDisabled` | `boolean` | `undefined` | 是否禁用且不可交互 |
| `isInvalid` | `boolean` | `false` | 是否无效（危险色） |
| `className` | `string` | `undefined` | 额外 CSS 类 |
| `animation` | `RadioRootAnimation` | - | 单选根动画配置 |
| `onSelectedChange` | `(isSelected: boolean) => void` | `undefined` | 选中状态变化时的回调 |
| `...PressableProps` | `PressableProps` | - | 支持全部标准 Pressable 属性（不含 disabled） |
#### RadioRenderProps
| prop | type | description |
| ------------ | --------- | ----------------------------- |
| `isSelected` | `boolean` | 是否选中 |
| `isDisabled` | `boolean` | 是否禁用 |
| `isInvalid` | `boolean` | 是否无效 |
#### RadioRootAnimation
单选根组件的动画配置，可为：
- `"disable-all"`：关闭包含子节点（Indicator、IndicatorThumb）在内的全部动画
- `undefined`：使用默认动画
### Radio.Indicator
| prop | type | default | description |
| ---------------------- | -------------------------- | ----------- | ------------------------------------------------ |
| `children` | `React.ReactNode` | `undefined` | 指示器内容 |
| `className` | `string` | `undefined` | 指示器额外 CSS 类 |
| `...AnimatedViewProps` | `AnimatedProps<ViewProps>` | - | 支持全部 Reanimated Animated.View 属性 |
### Radio.IndicatorThumb
| prop | type | default | description |
| ----------------------- | ------------------------------ | ----------- | ------------------------------------------------------------ |
| `className` | `string` | `undefined` | 拇指区域额外 CSS 类 |
| `animation` | `RadioIndicatorThumbAnimation` | - | 拇指动画配置 |
| `isAnimatedStyleActive` | `boolean` | `true` | 是否启用 Reanimated 动画样式 |
| `...AnimatedViewProps` | `AnimatedProps<ViewProps>` | - | 支持全部 Reanimated Animated.View 属性 |
#### RadioIndicatorThumbAnimation
单选指示器拇指的动画配置，可为：
- `false` 或 `"disabled"`：关闭全部动画
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| -------------------- | ----------------------- | ---------------------------------------------------- | ----------------------------------------------- |
| `state` | `'disabled' \| boolean` | - | 在自定义属性时用于禁用动画 |
| `scale.value` | `[number, number]` | `[1.5, 1]` | 缩放值 [未选中, 已选中] |
| `scale.timingConfig` | `WithTimingConfig` | `{ duration: 300, easing: Easing.out(Easing.ease) }` | 动画时间配置 |
**说明：** 标签、说明与错误信息请直接使用基础组件：
- 标签使用 [Label](../label/label.md)
- 说明使用 [Description](../description/description.md)
- 错误使用 [FieldError](../field-error/field-error.md)
## Hooks
### useRadioGroup
#### 返回值
| 属性 | 类型 | 描述 |
| --------------- | -------------------------- | ---------------------------------------------- |
| `value` | `string \| undefined` | 当前选中值 |
| `isDisabled` | `boolean` | 单选组是否禁用 |
| `isInvalid` | `boolean` | 单选组是否无效 |
| `variant` | `'primary' \| 'secondary'` | 单选组样式变体 |
| `onValueChange` | `(value: string) => void` | 修改选中值的函数 |
### useRadioGroupItem
#### 返回值
| 属性 | 类型 | 描述 |
| ------------------ | ---------------------------------------------- | ----------------------------------------------------------------------- |
| `isSelected` | `boolean` | 该选项是否选中 |
| `isDisabled` | `boolean \| undefined` | 该选项是否禁用 |
| `isInvalid` | `boolean \| undefined` | 该选项是否无效 |
| `variant` | `'primary' \| 'secondary' \| undefined` | 该选项的样式变体 |
| `onSelectedChange` | `((isSelected: boolean) => void) \| undefined` | 修改选中状态的回调（在组内选中该项） |
apps/docs/content/docs/cn/native/components/(forms)/search-field.mdx
+241
View File
@@ -0,0 +1,241 @@
---
title: SearchField 搜索框
description: 用于筛选与查询的复合搜索输入框。
links:
source_native: search-field/search-field.tsx
styles_native: search-field/search-field.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/search-field-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/search-field-docs-dark.mp4"
/>
## 导入
```tsx
import { SearchField } from 'heroui-native';
```
## 结构
```tsx
<SearchField value={value} onChange={onChange}>
<SearchField.Group>
<SearchField.SearchIcon />
<SearchField.Input />
<SearchField.ClearButton />
</SearchField.Group>
</SearchField>
```
- **SearchField**：根容器，接收 `value` 与 `onChange` 并通过上下文下发；同时提供 `isDisabled`、`isInvalid`、`isRequired` 与动画设置。
- **SearchField.Group**：横向 `flex-row` 容器，排列搜索图标、输入与清除按钮。
- **SearchField.SearchIcon**：默认放大镜图标，绝对定位在输入左侧；可传入子节点替换默认图标。
- **SearchField.Input**：包装 `Input` 并应用搜索相关默认行为；自动从上下文读取 `value` 与 `onChangeText`。
- **SearchField.ClearButton**：清除输入的小图标按钮；值为空时自动隐藏；按下时调用上下文的 `onChange("")`。
## 用法
### 基础用法
在根上传入 `value` 与 `onChange`；`Input` 与 `ClearButton` 通过上下文消费。
```tsx
<SearchField value={searchValue} onChange={setSearchValue}>
<SearchField.Group>
<SearchField.SearchIcon />
<SearchField.Input />
<SearchField.ClearButton />
</SearchField.Group>
</SearchField>
```
### 标签与说明
在 `Group` 外放置 `Label`、`Description` 以补充语义。
```tsx
<SearchField value={searchValue} onChange={setSearchValue}>
<Label>查找商品</Label>
<SearchField.Group>
<SearchField.SearchIcon />
<SearchField.Input />
<SearchField.ClearButton />
</SearchField.Group>
<Description>按名称、分类或 SKU 搜索</Description>
</SearchField>
```
### 校验
在根上使用 `isInvalid`、`isRequired`，并配合 `FieldError` 展示错误。
```tsx
<SearchField
value={searchValue}
onChange={setSearchValue}
isRequired
isInvalid={isInvalid}
>
<Label>搜索用户</Label>
<SearchField.Group>
<SearchField.SearchIcon />
<SearchField.Input />
<SearchField.ClearButton />
</SearchField.Group>
<Description hideOnInvalid>至少输入 3 个字符再搜索</Description>
<FieldError>未找到结果，请尝试其他关键词。</FieldError>
</SearchField>
```
### 自定义搜索图标
向 `SearchField.SearchIcon` 传入子节点替换默认图标。
```tsx
<SearchField value={searchValue} onChange={setSearchValue}>
<SearchField.Group>
<SearchField.SearchIcon>
<Text className="text-base">🔍</Text>
</SearchField.SearchIcon>
<SearchField.Input className="pl-10" />
<SearchField.ClearButton />
</SearchField.Group>
</SearchField>
```
### 禁用
根上设置 `isDisabled`，通过上下文禁用子级。
```tsx
<SearchField value="之前的查询" isDisabled>
<Label>已禁用的搜索</Label>
<SearchField.Group>
<SearchField.SearchIcon />
<SearchField.Input />
</SearchField.Group>
<Description>搜索暂时不可用</Description>
</SearchField>
```
## 示例
```tsx
import { Description, Label, SearchField } from 'heroui-native';
import { useState } from 'react';
import { View } from 'react-native';
export default function SearchFieldExample() {
const [searchValue, setSearchValue] = useState('');
return (
<View className="px-5">
<SearchField value={searchValue} onChange={setSearchValue}>
<Label>查找商品</Label>
<SearchField.Group>
<SearchField.SearchIcon />
<SearchField.Input />
<SearchField.ClearButton />
</SearchField.Group>
<Description>按名称、分类或 SKU 搜索</Description>
</SearchField>
</View>
);
}
```
更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/search-field.tsx>)。
## API 参考
### SearchField
| prop | type | default | description |
| -------------- | ------------------------- | ------- | -------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 搜索字段内的子节点 |
| `value` | `string` | - | 受控搜索文本 |
| `onChange` | `(value: string) => void` | - | 文本变化回调 |
| `isDisabled` | `boolean` | `false` | 是否禁用 |
| `isInvalid` | `boolean` | `false` | 是否非法 |
| `isRequired` | `boolean` | `false` | 是否必填 |
| `className` | `string` | - | 额外的 class |
| `animation` | `AnimationRootDisableAll` | - | 搜索字段动画配置 |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部属性 |
#### AnimationRootDisableAll
根动画配置，可为：
- `"disable-all"`：禁用全部动画（含子级，级联）
- `undefined`：使用默认动画
### SearchField.Group
| prop | type | default | description |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | - | 组内子节点 |
| `className` | `string` | - | 额外的 class |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部属性 |
### SearchField.SearchIcon
| prop | type | default | description |
| -------------- | -------------------------------- | ------- | ---------------------------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 自定义内容，替换默认搜索图标 |
| `className` | `string` | - | 额外的 class |
| `iconProps` | `SearchFieldSearchIconIconProps` | - | 自定义默认搜索图标（提供 `children` 时忽略） |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部属性 |
#### SearchFieldSearchIconIconProps
| prop | type | default | description |
| ------- | -------- | ------------------- | ----------- |
| `size` | `number` | `16` | 图标尺寸 |
| `color` | `string` | 主题的 `muted` 色 | 图标颜色 |
### SearchField.Input
在 [Input](./input) 属性之上带有搜索默认值（`placeholder="Search..."`、`returnKeyType="search"`、`accessibilityRole="search"`）。不提供 `value` 与 `onChangeText`，由 `SearchField` 上下文提供。
### SearchField.ClearButton
受控 `value` 为空字符串时自动隐藏；按下时调用上下文的 `onChange("")`。若额外传入 `onPress`，会在清空后调用。
| prop | type | default | description |
| ---------------- | --------------------------------- | ------- | ------------------------------------------------ |
| `children` | `React.ReactNode` | - | 自定义内容，替换默认关闭图标 |
| `iconProps` | `SearchFieldClearButtonIconProps` | - | 清除按钮图标属性 |
| `className` | `string` | - | 额外的 class |
| `...ButtonProps` | `ButtonRootProps` | - | 支持 Button 根级全部属性 |
#### SearchFieldClearButtonIconProps
| prop | type | default | description |
| ------- | -------- | ------------------- | ----------- |
| `size` | `number` | `14` | 图标尺寸 |
| `color` | `string` | 主题的 `muted` 色 | 图标颜色 |
## Hooks
### useSearchField
访问搜索字段上下文，必须在 `SearchField` 内使用。
```tsx
import { useSearchField } from 'heroui-native';
const { value, onChange, isDisabled, isInvalid, isRequired } = useSearchField();
```
#### 返回值
| property | type | description |
| ------------ | ---------------------------------------- | --------------------- |
| `value` | `string \| undefined` | 当前受控搜索文本 |
| `onChange` | `((value: string) => void) \| undefined` | 更新搜索文本的回调 |
| `isDisabled` | `boolean` | 是否禁用 |
| `isInvalid` | `boolean` | 是否非法 |
| `isRequired` | `boolean` | 是否必填 |
apps/docs/content/docs/cn/native/components/(forms)/select.mdx
+822
View File
@@ -0,0 +1,822 @@
---
title: Select 选择器
description: 通过按钮触发，展示可选列表供用户选择。
icon: updated
links:
source_native: select/select.tsx
styles_native: select/select.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/select-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/select-docs-dark.mp4"
/>
## 导入
```tsx
import { Select } from 'heroui-native';
```
## 结构
```tsx
<Select>
<Select.Trigger>
<Select.Value />
<Select.TriggerIndicator />
</Select.Trigger>
<Select.Portal>
<Select.Overlay />
<Select.Content>
<Select.Close />
<Select.ListLabel>...</Select.ListLabel>
<Select.Item>
<Select.ItemLabel />
<Select.ItemDescription>...</Select.ItemDescription>
<Select.ItemIndicator />
</Select.Item>
</Select.Content>
</Select.Portal>
</Select>
```
- **Select**：根容器，管理打开/关闭、选中值，并向子组件提供上下文。
- **Select.Trigger**：可点击的触发器，用于切换选择器显示。为任意子元素包裹按压处理，支持 `variant`（`'default'` 或 `'unstyled'`）。
- **Select.Value**：显示当前选中值或占位符；选中变化时自动更新，样式随是否有选中值变化。
- **Select.TriggerIndicator**：可选的视觉指示器，表示开/关状态；默认渲染带动画的双角标，随打开/关闭旋转。
- **Select.Portal**：在Portal层渲染内容，保证正确的层级与定位。
- **Select.Overlay**：可选的背景遮罩，可透明或半透明，用于捕获外部点击。
- **Select.Content**：内容容器，支持三种呈现：气泡（浮动定位）、底部抽屉或对话框。
- **Select.Close**：关闭按钮；可传入自定义子节点，否则使用默认关闭图标。
- **Select.ListLabel**：列表标题，使用预设排版样式。
- **Select.Item**：可选中的选项，处理选中态与按压。
- **Select.ItemLabel**：选项主文案。
- **Select.ItemDescription**：可选的说明文字，弱化样式。
- **Select.ItemIndicator**：选中项的可选指示器，默认渲染对勾图标。
## 用法
### 基础用法
Select 通过复合子组件构建下拉选择界面。
```tsx
<Select>
<Select.Trigger>...</Select.Trigger>
<Select.Portal>
<Select.Overlay />
<Select.Content presentation="popover">
<Select.Item value="1" label="选项 1" />
<Select.Item value="2" label="选项 2" />
</Select.Content>
</Select.Portal>
</Select>
```
### 在触发器显示选中值
使用 Value 在触发器区域展示当前选中项。
```tsx
<Select>
<Select.Trigger>
<Select.Value placeholder="请选择一项" />
<Select.TriggerIndicator />
</Select.Trigger>
<Select.Portal>
<Select.Overlay />
<Select.Content presentation="popover">
<Select.Item value="apple" label="苹果" />
<Select.Item value="orange" label="橙子" />
<Select.Item value="banana" label="香蕉" />
</Select.Content>
</Select.Portal>
</Select>
```
### 气泡（Popover）呈现
使用 `presentation="popover"` 获得带自动定位的浮动内容。
```tsx
<Select>
<Select.Trigger>...</Select.Trigger>
<Select.Portal>
<Select.Overlay />
<Select.Content presentation="popover" placement="bottom" align="center">
<Select.Item value="1" label="项 1" />
<Select.Item value="2" label="项 2" />
</Select.Content>
</Select.Portal>
</Select>
```
### 宽度控制
通过 `width` 控制内容宽度；仅对气泡呈现生效。
```tsx
{
/* 固定像素宽度 */
}
<Select>
<Select.Trigger>...</Select.Trigger>
<Select.Portal>
<Select.Overlay />
<Select.Content presentation="popover" width={280}>
<Select.Item value="1" label="项 1" />
</Select.Content>
</Select.Portal>
</Select>;
{
/* 与触发器同宽 */
}
<Select>
<Select.Trigger>...</Select.Trigger>
<Select.Portal>
<Select.Overlay />
<Select.Content presentation="popover" width="trigger">
<Select.Item value="1" label="项 1" />
</Select.Content>
</Select.Portal>
</Select>;
{
/* 全宽（100%） */
}
<Select>
<Select.Trigger>...</Select.Trigger>
<Select.Portal>
<Select.Overlay />
<Select.Content presentation="popover" width="full">
<Select.Item value="1" label="项 1" />
</Select.Content>
</Select.Portal>
</Select>;
{
/* 随内容自适应（默认） */
}
<Select>
<Select.Trigger>...</Select.Trigger>
<Select.Portal>
<Select.Overlay />
<Select.Content presentation="popover" width="content-fit">
<Select.Item value="1" label="项 1" />
</Select.Content>
</Select.Portal>
</Select>;
```
### 底部抽屉呈现
使用底部抽屉以获得更贴近移动端的体验。
```tsx
<Select presentation="bottom-sheet">
<Select.Trigger>...</Select.Trigger>
<Select.Portal>
<Select.Overlay />
<Select.Content presentation="bottom-sheet" snapPoints={['35%']}>
<Select.Item value="1" label="项 1" />
<Select.Item value="2" label="项 2" />
</Select.Content>
</Select.Portal>
</Select>
```
### 对话框呈现
使用对话框呈现居中模态式选择。
```tsx
<Select presentation="dialog">
<Select.Trigger>...</Select.Trigger>
<Select.Portal>
<Select.Overlay />
<Select.Content presentation="dialog">
<Select.Close />
<Select.ListLabel>请选择一项</Select.ListLabel>
<Select.Item value="1" label="项 1" />
<Select.Item value="2" label="项 2" />
</Select.Content>
</Select.Portal>
</Select>
```
### 自定义选项内容
通过自定义子节点与指示器定制选项外观。
```tsx
<Select>
<Select.Trigger>...</Select.Trigger>
<Select.Portal>
<Select.Overlay />
<Select.Content presentation="popover">
<Select.Item value="us" label="美国">
<View className="flex-row items-center gap-3 flex-1">
<Text>🇺🇸</Text>
<Select.ItemLabel />
</View>
<Select.ItemIndicator />
</Select.Item>
<Select.Item value="uk" label="英国">
<View className="flex-row items-center gap-3 flex-1">
<Text>🇬🇧</Text>
<Select.ItemLabel />
</View>
<Select.ItemIndicator />
</Select.Item>
</Select.Content>
</Select.Portal>
</Select>
```
### 使用渲染函数
在 `Select.Item` 上使用渲染函数，根据选中态等自定义内容。
```tsx
<Select>
<Select.Trigger>...</Select.Trigger>
<Select.Portal>
<Select.Overlay />
<Select.Content presentation="popover">
<Select.Item value="us" label="美国">
{({ isSelected, value, isDisabled }) => (
<>
<View className="flex-row items-center gap-3 flex-1">
<Text>🇺🇸</Text>
<Select.ItemLabel
className={
isSelected ? 'text-accent font-medium' : 'text-foreground'
}
/>
</View>
<Select.ItemIndicator />
</>
)}
</Select.Item>
<Select.Item value="uk" label="英国">
{({ isSelected }) => (
<>
<View className="flex-row items-center gap-3 flex-1">
<Text>🇬🇧</Text>
<Select.ItemLabel
className={
isSelected ? 'text-accent font-medium' : 'text-foreground'
}
/>
</View>
<Select.ItemIndicator />
</>
)}
</Select.Item>
</Select.Content>
</Select.Portal>
</Select>
```
### 带选项说明
为选项添加说明以提供更多上下文。
```tsx
<Select>
<Select.Trigger>...</Select.Trigger>
<Select.Portal>
<Select.Overlay />
<Select.Content presentation="popover">
<Select.Item value="basic" label="基础版">
<View className="flex-1">
<Select.ItemLabel />
<Select.ItemDescription>
面向个人使用的必备功能
</Select.ItemDescription>
</View>
<Select.ItemIndicator />
</Select.Item>
</Select.Content>
</Select.Portal>
</Select>
```
### 带触发器指示器
添加视觉指示器表示开/关状态；打开/关闭时会旋转。
```tsx
<Select>
<Select.Trigger>
<Select.Value placeholder="请选择一项" />
<Select.TriggerIndicator />
</Select.Trigger>
<Select.Portal>
<Select.Overlay />
<Select.Content presentation="popover">
<Select.Item value="1" label="选项 1" />
<Select.Item value="2" label="选项 2" />
</Select.Content>
</Select.Portal>
</Select>
```
### 无样式触发器与自定义组合
使用 `unstyled` 变体，将触发器与 Button 等组件组合。
```tsx
<Select>
<Select.Trigger variant="unstyled" asChild>
<Button variant="secondary">
<Select.Value placeholder="请选择…" />
<Select.TriggerIndicator />
</Button>
</Select.Trigger>
<Select.Portal>
<Select.Overlay />
<Select.Content presentation="popover">
<Select.Item value="1" label="选项 1" />
<Select.Item value="2" label="选项 2" />
</Select.Content>
</Select.Portal>
</Select>
```
### 受控模式
以编程方式控制打开状态与选中值。
```tsx
const [value, setValue] = useState();
const [isOpen, setIsOpen] = useState(false);
<Select
value={value}
onValueChange={setValue}
isOpen={isOpen}
onOpenChange={setIsOpen}
>
<Select.Trigger>
<Select.Value placeholder="请选择…" />
<Select.TriggerIndicator />
</Select.Trigger>
<Select.Portal>
<Select.Overlay />
<Select.Content presentation="popover">
<Select.Item value="1" label="选项 1" />
<Select.Item value="2" label="选项 2" />
</Select.Content>
</Select.Portal>
</Select>;
```
## 示例
```tsx
import { Select, Separator } from 'heroui-native';
import React, { useState } from 'react';
type SelectOption = {
value: string;
label: string;
};
const US_STATES: SelectOption[] = [
{ value: 'CA', label: '加利福尼亚' },
{ value: 'NY', label: '纽约' },
{ value: 'TX', label: '得克萨斯' },
{ value: 'FL', label: '佛罗里达' },
];
export default function SelectExample() {
const [value, setValue] = useState<SelectOption | undefined>();
return (
<Select value={value} onValueChange={setValue}>
<Select.Trigger>
<Select.Value placeholder="请选择一项" />
<Select.TriggerIndicator />
</Select.Trigger>
<Select.Portal>
<Select.Overlay />
<Select.Content presentation="popover" width="trigger">
<Select.ListLabel className="mb-2">选择州/省</Select.ListLabel>
{US_STATES.map((state, index) => (
<React.Fragment key={state.value}>
<Select.Item value={state.value} label={state.label} />
{index < US_STATES.length - 1 && <Separator />}
</React.Fragment>
))}
</Select.Content>
</Select.Portal>
</Select>
);
}
```
更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/select.tsx)。
## API 参考
### Select
| prop | type | default | description |
| --------------- | ----------------------------------------- | ----------- | ---------------------------------------------------------------------- |
| `children` | `ReactNode` | - | 选择器子内容 |
| `value` | `SelectOption \| SelectOption[]` | - | 当前选中值（受控） |
| `onValueChange` | `(value: SelectOption \| SelectOption[]) => void` | - | 选中值变化时的回调 |
| `defaultValue` | `SelectOption \| SelectOption[]` | - | 默认选中值（非受控） |
| `isOpen` | `boolean` | - | 是否打开（受控） |
| `isDefaultOpen` | `boolean` | - | 初始是否打开（非受控） |
| `onOpenChange` | `(isOpen: boolean) => void` | - | 打开状态变化时的回调 |
| `isDisabled` | `boolean` | `false` | 是否禁用 |
| `presentation` | `'popover' \| 'bottom-sheet' \| 'dialog'` | `'popover'` | 内容呈现方式 |
| `animation` | `SelectRootAnimation` | - | 动画配置 |
| `asChild` | `boolean` | `false` | 是否将子元素作为实际渲染节点 |
| `...ViewProps` | `ViewProps` | - | 支持全部标准 React Native `View` 属性 |
#### SelectRootAnimation
Select 根级动画配置，可为：
- `false` 或 `"disabled"`：仅禁用根动画
- `"disable-all"`：禁用根与子级全部动画
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| ---------------- | ------------------------------------------------ | ------- | ----------------------------------------------- |
| `state` | `'disabled' \| 'disable-all' \| boolean` | - | 在自定义属性时用于禁用动画 |
| `entering.value` | `SpringAnimationConfig \| TimingAnimationConfig` | - | 打开时的动画配置 |
| `exiting.value` | `SpringAnimationConfig \| TimingAnimationConfig` | - | 关闭时的动画配置 |
#### SpringAnimationConfig
| prop | type | default | description |
| -------- | ------------------ | ------- | ----------------------------------------- |
| `type` | `'spring'` | - | 动画类型（须为 `'spring'`） |
| `config` | `WithSpringConfig` | - | Reanimated 弹簧动画配置 |
#### TimingAnimationConfig
| prop | type | default | description |
| -------- | ------------------ | ------- | ----------------------------------------- |
| `type` | `'timing'` | - | 动画类型（须为 `'timing'`） |
| `config` | `WithTimingConfig` | - | Reanimated 时长动画配置 |
### Select.Trigger
| prop | type | default | description |
| ------------------- | ------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------- |
| `variant` | `'default' \| 'unstyled'` | `'default'` | 触发器变体：`'default'` 应用预设容器样式，`'unstyled'` 移除默认样式 |
| `children` | `ReactNode` | - | 触发器内容 |
| `className` | `string` | - | 触发器额外 class |
| `asChild` | `boolean` | `true` | 是否将子元素作为实际渲染节点 |
| `isDisabled` | `boolean` | - | 是否禁用触发器 |
| `...PressableProps` | `PressableProps` | - | 支持全部标准 React Native `Pressable` 属性 |
### Select.Value
| prop | type | default | description |
| -------------- | ----------- | ------- | -------------------------------------------------- |
| `placeholder` | `string` | - | 未选中时的占位文案 |
| `className` | `string` | - | 值区域额外 class |
| `...TextProps` | `TextProps` | - | 支持全部标准 React Native `Text` 属性 |
**说明：** 值组件会根据是否有选中项自动应用不同文字颜色：
- 已选中：`text-foreground`
- 未选中（占位）：`text-field-placeholder`
### Select.TriggerIndicator
| prop | type | default | description |
| ----------------------- | --------------------------------- | ------- | ------------------------------------------------------------ |
| `children` | `ReactNode` | - | 自定义指示器内容；默认带动画的双角标 |
| `className` | `string` | - | 指示器额外 class |
| `style` | `ViewStyle` | - | 指示器自定义样式 |
| `iconProps` | `SelectTriggerIndicatorIconProps` | - | 双角标图标配置 |
| `animation` | `SelectTriggerIndicatorAnimation` | - | 动画配置 |
| `isAnimatedStyleActive` | `boolean` | `true` | 是否启用 Reanimated 动画样式 |
| `...ViewProps` | `ViewProps` | - | 支持全部标准 React Native `View` 属性 |
**说明：** 以下样式属性由动画占用，不能通过 `className` 设置：
- `transform`（尤其是 `rotate`）— 用于开/关旋转过渡
若要自定义，请使用 `animation`。若需完全关闭动画样式并自行用 `className` 或 `style` 控制，请设置 `isAnimatedStyleActive={false}`。
#### SelectTriggerIndicatorIconProps
| prop | type | default | description |
| ------- | -------- | ------- | ------------------------------------------------------ |
| `size` | `number` | `16` | 图标尺寸 |
| `color` | `string` | - | 图标颜色（默认同前景主题色） |
#### SelectTriggerIndicatorAnimation
`Select.TriggerIndicator` 的动画配置，可为：
- `false` 或 `"disabled"`：禁用全部动画
- `true` 或 `undefined`：使用默认动画（0° 到 -180° 旋转）
- `object`：自定义动画配置
| prop | type | default | description |
| ----------------------- | ----------------------- | -------------------------------------------- | ----------------------------------------------- |
| `state` | `'disabled' \| boolean` | - | 在自定义属性时用于禁用动画 |
| `rotation.value` | `[number, number]` | `[0, -180]` | 旋转角度 [关闭, 打开]，单位度 |
| `rotation.springConfig` | `WithSpringConfig` | `{ damping: 140, stiffness: 1000, mass: 4 }` | 旋转弹簧动画配置 |
### Select.Portal
| prop | type | default | description |
| -------------------------- | ----------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `children` | `ReactNode` | - | Portal内容（必填） |
| `disableFullWindowOverlay` | `boolean` | `false` | 在 iOS 为 `true` 时使用 `View` 代替 `FullWindowOverlay`，便于元素检查器；遮罩将无法叠在原生模态之上 |
| `unstable_accessibilityContainerViewIsModal` | `boolean` | `false` | 控制 VoiceOver 是否将遮罩窗口视为模态容器。为 `true` 时，VoiceOver 仅聚焦遮罩内元素。仅 iOS；API 不稳定，可能随 react-native-screens 变更 |
| `className` | `string` | - | Portal容器额外 class |
| `hostName` | `string` | - | Portal宿主元素的可选名称 |
| `forceMount` | `boolean` | - | 是否强制挂载到 DOM |
| `...ViewProps` | `ViewProps` | - | 支持全部标准 React Native `View` 属性 |
### Select.Overlay
| prop | type | default | description |
| ----------------------- | ------------------------ | ------- | ------------------------------------------------------------ |
| `className` | `string` | - | 遮罩额外 class |
| `animation` | `SelectOverlayAnimation` | - | 动画配置 |
| `isAnimatedStyleActive` | `boolean` | `true` | 是否启用 Reanimated 动画样式 |
| `closeOnPress` | `boolean` | `true` | 点击遮罩是否关闭选择器 |
| `forceMount` | `boolean` | - | 是否强制挂载到 DOM |
| `asChild` | `boolean` | `false` | 是否将子元素作为实际渲染节点 |
| `...Animated.ViewProps` | `Animated.ViewProps` | - | 支持 Reanimated `Animated.View` 的全部属性 |
#### SelectOverlayAnimation
`Select.Overlay` 的动画配置，可为：
- `false` 或 `"disabled"`：禁用全部动画
- `true` 或 `undefined`：使用默认动画（底部抽屉/对话框为基于进度的透明度；气泡为关键帧动画）
- `object`：自定义动画配置
| prop | type | default | description |
| --------------- | -------------------------- | ----------- | ---------------------------------------------------------------------------- |
| `state` | `'disabled' \| boolean` | - | 在自定义属性时用于禁用动画 |
| `opacity.value` | `[number, number, number]` | `[0, 1, 0]` | 透明度 [空闲, 打开, 关闭]（用于底部抽屉/对话框呈现） |
| `entering` | `EntryOrExitLayoutType` | - | 进入过渡自定义关键帧（用于气泡呈现） |
| `exiting` | `EntryOrExitLayoutType` | - | 退出过渡自定义关键帧（用于气泡呈现） |
### Select.Content（气泡呈现）
| prop | type | default | description |
| ----------------------- | ------------------------------------------------ | --------------- | ------------------------------------------------------ |
| `children` | `ReactNode` | - | 选择器内容 |
| `width` | `number \| 'trigger' \| 'content-fit' \| 'full'` | `'content-fit'` | 内容宽度策略 |
| `presentation` | `'popover'` | `'popover'` | 呈现模式 |
| `placement` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | 相对触发器的方位 |
| `align` | `'start' \| 'center' \| 'end'` | `'center'` | 沿放置轴的对齐方式 |
| `avoidCollisions` | `boolean` | `true` | 靠近视口边缘时是否翻转 placement |
| `offset` | `number` | `8` | 与触发器的间距（像素） |
| `alignOffset` | `number` | `0` | 沿对齐轴的偏移（像素） |
| `className` | `string` | - | 内容容器额外 class |
| `animation` | `SelectContentPopoverAnimation` | - | 动画配置 |
| `forceMount` | `boolean` | - | 是否强制挂载到 DOM |
| `insets` | `Insets` | - | 定位时需遵守的屏幕边距 |
| `asChild` | `boolean` | `false` | 是否将子元素作为实际渲染节点 |
| `...Animated.ViewProps` | `Animated.ViewProps` | - | 支持 Reanimated `Animated.View` 的全部属性 |
#### SelectContentPopoverAnimation
`Select.Content`（气泡呈现）的动画配置，可为：
- `false` 或 `"disabled"`：禁用全部动画
- `true` 或 `undefined`：使用默认关键帧（按 placement 的 translateY/translateX、scale、opacity）
- `object`：自定义 `entering` 和/或 `exiting` 关键帧
| prop | type | default | description |
| ---------- | ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `state` | `'disabled' \| boolean` | - | 在自定义属性时用于禁用动画 |
| `entering` | `EntryOrExitLayoutType` | - | 进入过渡关键帧（默认：按 placement 的 translateY/translateX、scale、opacity，200ms） |
| `exiting` | `EntryOrExitLayoutType` | - | 退出过渡关键帧（默认：与进入镜像，150ms） |
### Select.Content（底部抽屉呈现）
| prop | type | default | description |
| --------------------------- | ------------------ | ------- | ------------------------------------------------ |
| `children` | `ReactNode` | - | 底部抽屉内容 |
| `presentation` | `'bottom-sheet'` | - | 呈现模式 |
| `contentContainerClassName` | `string` | - | 内容容器额外 class |
| `...BottomSheetProps` | `BottomSheetProps` | - | 支持 `@gorhom/bottom-sheet` 的全部属性 |
### Select.Content（对话框呈现）
| prop | type | default | description |
| -------------- | -------------------------------------------------------- | ------- | --------------------------------------------------- |
| `children` | `ReactNode` | - | 对话框内容 |
| `presentation` | `'dialog'` | - | 呈现模式 |
| `classNames` | `{ wrapper?: string; content?: string }` | - | 包裹层与内容区额外 class |
| `styles` | `Partial<Record<DialogContentFallbackSlots, ViewStyle>>` | - | 对话框各部分的样式 |
| `animation` | `SelectContentAnimation` | - | 动画配置 |
| `isSwipeable` | `boolean` | `true` | 是否允许滑动关闭 |
| `forceMount` | `boolean` | - | 是否强制挂载到 DOM |
| `asChild` | `boolean` | `false` | 是否将子元素作为实际渲染节点 |
| `...ViewProps` | `ViewProps` | - | 支持全部标准 React Native `View` 属性 |
#### `styles`
| prop | type | description |
| --------- | ----------- | -------------------------------- |
| `wrapper` | `ViewStyle` | 外层包裹容器样式 |
| `content` | `ViewStyle` | 对话框内容区样式 |
#### SelectContentAnimation
`Select.Content`（对话框呈现）的动画配置，可为：
- `false` 或 `"disabled"`：禁用全部动画
- `true` 或 `undefined`：使用默认关键帧（scale 与 opacity）
- `object`：自定义 `entering` 和/或 `exiting` 关键帧
| prop | type | default | description |
| ---------- | ----------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
| `state` | `'disabled' \| boolean` | - | 在自定义属性时用于禁用动画 |
| `entering` | `EntryOrExitLayoutType` | - | 进入过渡关键帧（默认：scale 与 opacity，200ms） |
| `exiting` | `EntryOrExitLayoutType` | - | 退出过渡关键帧（默认：与进入镜像，150ms） |
### Select.Close
`Select.Close` 继承 [CloseButton](./close-button)，按下时自动关闭选择器。
### Select.ListLabel
| prop | type | default | description |
| -------------- | ----------- | ------- | -------------------------------------------------- |
| `children` | `ReactNode` | - | 列表标题文案 |
| `className` | `string` | - | 列表标题额外 class |
| `...TextProps` | `TextProps` | - | 支持全部标准 React Native `Text` 属性 |
### Select.Item
| prop | type | default | description |
| ------------------- | ------------------------------------------------------------ | ------- | -------------------------------------------------------------------------- |
| `children` | `ReactNode \| ((props: SelectItemRenderProps) => ReactNode)` | - | 自定义选项内容；默认可为标签+指示器，或渲染函数 |
| `value` | `any` | - | 选项关联的值（必填） |
| `label` | `string` | - | 选项标签文案（必填） |
| `isDisabled` | `boolean` | `false` | 是否禁用该选项 |
| `className` | `string` | - | 选项额外 class |
| `...PressableProps` | `PressableProps` | - | 支持全部标准 React Native `Pressable` 属性 |
#### SelectItemRenderProps
使用渲染函数作为 `children` 时，会传入以下属性：
| property | type | description |
| ------------ | --------- | --------------------------------------- |
| `isSelected` | `boolean` | 当前项是否选中 |
| `value` | `string` | 当前项的值 |
| `isDisabled` | `boolean` | 当前项是否禁用 |
### Select.ItemLabel
| prop | type | default | description |
| -------------- | ----------- | ------- | -------------------------------------------------- |
| `className` | `string` | - | 选项标签额外 class |
| `...TextProps` | `TextProps` | - | 支持全部标准 React Native `Text` 属性 |
### Select.ItemDescription
| prop | type | default | description |
| -------------- | ----------- | ------- | -------------------------------------------------- |
| `children` | `ReactNode` | - | 说明文案 |
| `className` | `string` | - | 说明额外 class |
| `...TextProps` | `TextProps` | - | 支持全部标准 React Native `Text` 属性 |
### Select.ItemIndicator
| prop | type | default | description |
| -------------- | ------------------------------ | ------- | -------------------------------------------------- |
| `children` | `ReactNode` | - | 自定义指示器；默认对勾图标 |
| `className` | `string` | - | 指示器额外 class |
| `iconProps` | `SelectItemIndicatorIconProps` | - | 对勾图标配置 |
| `...ViewProps` | `ViewProps` | - | 支持全部标准 React Native `View` 属性 |
#### SelectItemIndicatorIconProps
| prop | type | default | description |
| ------- | -------- | ---------------- | ----------------- |
| `size` | `number` | `16` | 图标尺寸 |
| `color` | `string` | 主题 accent-soft-foreground 颜色 | 图标颜色 |
## Hooks
### useSelect
用于读取 Select 根上下文，返回状态与控制方法。
```tsx
import { useSelect } from 'heroui-native';
const {
isOpen,
onOpenChange,
isDefaultOpen,
isDisabled,
presentation,
triggerPosition,
setTriggerPosition,
contentLayout,
setContentLayout,
nativeID,
value,
onValueChange,
} = useSelect();
```
#### 返回值
| property | type | description |
| -------------------- | -------------------------------------------- | --------------------------------------------------------- |
| `isOpen` | `boolean` | 当前是否打开 |
| `onOpenChange` | `(open: boolean) => void` | 修改打开状态的回调 |
| `isDefaultOpen` | `boolean \| undefined` | 默认是否打开（非受控） |
| `isDisabled` | `boolean \| undefined` | 是否禁用 |
| `presentation` | `'popover' \| 'bottom-sheet' \| 'dialog'` | 内容呈现方式 |
| `triggerPosition` | `LayoutPosition \| null` | 触发器相对视口的位置 |
| `setTriggerPosition` | `(position: LayoutPosition \| null) => void` | 更新触发器位置 |
| `contentLayout` | `LayoutRectangle \| null` | 选择器内容的布局测量 |
| `setContentLayout` | `(layout: LayoutRectangle \| null) => void` | 更新内容布局测量 |
| `nativeID` | `string` | 当前实例的唯一标识 |
| `value` | `SelectOption \| SelectOption[]` | 当前选中项 |
| `onValueChange` | `(option: SelectOption \| SelectOption[]) => void` | 选中值变化时的回调 |
**说明：** 必须在 `Select` 内使用；在上下文外调用将抛错。
### useSelectAnimation
用于在自定义或复合子组件中读取 Select 动画相关共享值。
```tsx
import { useSelectAnimation } from 'heroui-native';
const { selectState, progress, isDragging, isGestureReleaseAnimationRunning } =
useSelectAnimation();
```
#### 返回值
| property | type | description |
| ---------------------------------- | ---------------------- | ---------------------------------------------------------- |
| `progress` | `SharedValue<number>` | 动画进度（0=空闲，1=打开，2=关闭） |
| `isDragging` | `SharedValue<boolean>` | 内容是否正在被拖拽 |
| `isGestureReleaseAnimationRunning` | `SharedValue<boolean>` | 手势释放后的动画是否正在运行 |
**说明：** 必须在 `Select` 内使用；在动画上下文外调用将抛错。
#### SelectOption
| property | type | description |
| -------- | -------- | ---------------------------- |
| `value` | `string` | 选项值 |
| `label` | `string` | 选项显示标签 |
### useSelectItem
用于读取 Select Item 上下文，返回当前项的值与标签。
```tsx
import { useSelectItem } from 'heroui-native';
const { itemValue, label } = useSelectItem();
```
#### 返回值
| property | type | description |
| ----------- | -------- | ---------------------------------- |
| `itemValue` | `string` | 当前项的值 |
| `label` | `string` | 当前项的标签文案 |
## 特别说明
### 元素检查器（iOS）
Select 在 iOS 上使用 `FullWindowOverlay`。开发时若需启用 React Native 元素检查器，请在 `Select.Portal` 上设置 `disableFullWindowOverlay={true}`。代价是下拉层将无法叠在原生模态之上。
### 原生模态（iOS）
当 `Select` 位于以原生模态形式呈现的页面内时（`presentation: 'modal' | 'formSheet' | 'pageSheet'`），下拉层可能会向上偏移渲染。在新架构（Fabric）中，`react-native-screens` 将 `RNSModalScreen` 标记为 Fabric 根节点，因此触发器的坐标是相对于模态原点上报的，而 `FullWindowOverlay`（下拉层挂载点）锚定在 iOS 应用窗口上。可通过将 `safeAreaInsets.top` 加到 `offset` 来补偿：
```tsx
import { useSafeAreaInsets } from 'react-native-safe-area-context';
const insets = useSafeAreaInsets();
<Select.Content presentation="popover" offset={insets.top + 10}>
...
</Select.Content>;
```
apps/docs/content/docs/cn/native/components/(forms)/text-area.mdx
+140
View File
@@ -0,0 +1,140 @@
---
title: TextArea 多行文本框
description: 多行文本输入，带样式边框与背景，用于收集较长内容。
links:
source_native: text-area/text-area.tsx
styles_native: text-area/text-area.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/text-area-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/text-area-docs-dark.mp4"
/>
## 导入
```tsx
import { TextArea } from 'heroui-native';
```
## 用法
### 基础用法
`TextArea` 可单独使用，也可放在 `TextField` 内。
```tsx
import { TextArea } from 'heroui-native';
<TextArea placeholder="请输入留言" />
```
### 与 TextField 组合
与 `TextField` 搭配形成完整表单结构。
```tsx
import { Description, Label, TextArea, TextField } from 'heroui-native';
<TextField>
<Label>留言</Label>
<TextArea placeholder="请在此输入留言…" />
<Description>请尽量提供详细信息。</Description>
</TextField>
```
### 校验状态
非法时展示错误样式。
```tsx
import { FieldError, Label, TextArea, TextField } from 'heroui-native';
<TextField isRequired isInvalid={true}>
<Label>留言</Label>
<TextArea placeholder="请输入留言" />
<FieldError>请输入有效留言</FieldError>
</TextField>
```
### 禁用状态
禁用后不可编辑。
```tsx
import { Label, TextArea, TextField } from 'heroui-native';
<TextField isDisabled>
<Label>禁用字段</Label>
<TextArea placeholder="不可编辑" value="只读内容" />
</TextField>
```
### 变体
按场景使用不同视觉变体。
```tsx
import { Label, TextArea, TextField } from 'heroui-native';
<TextField>
<Label>主要变体</Label>
<TextArea placeholder="主要样式文本域" variant="primary" />
</TextField>
<TextField>
<Label>次要变体</Label>
<TextArea placeholder="次要样式文本域" variant="secondary" />
</TextField>
```
### 自定义样式
通过 `className` 自定义外观。
```tsx
import { Label, TextArea, TextField } from 'heroui-native';
<TextField>
<Label>自定义样式</Label>
<TextArea
placeholder="自定义颜色"
className="bg-blue-50 border-blue-500 focus:border-blue-700"
/>
</TextField>
```
## 示例
```tsx
import { Description, FieldError, Label, TextArea, TextField } from 'heroui-native';
import { View } from 'react-native';
export default function TextAreaExample() {
return (
<View className="gap-8">
<TextField>
<Label>主要变体</Label>
<TextArea placeholder="主要样式文本域" variant="primary" />
<Description>默认变体，主要样式</Description>
</TextField>
<TextField>
<Label>次要变体</Label>
<TextArea
placeholder="次要样式文本域"
variant="secondary"
/>
<Description>用于表面上的次要变体</Description>
</TextField>
</View>
);
}
```
更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/text-area.tsx)。
## API 参考
`TextArea` 继承 [Input](./input) 的全部属性。区别仅为默认值：`multiline` 默认为 `true`，`textAlignVertical` 默认为 `'top'`。
apps/docs/content/docs/cn/native/components/(forms)/text-field.mdx
+266
View File
@@ -0,0 +1,266 @@
---
title: TextField 文本输入框
description: 带标签、说明与错误处理的文本输入，用于收集用户输入。
links:
source_native: text-field/text-field.tsx
styles_native: text-field/text-field.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/text-field-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/text-field-docs-dark.mp4"
/>
## 导入
```tsx
import { TextField } from 'heroui-native';
```
## 结构
```tsx
<TextField>
<Label>...</Label>
<Input />
<Description>...</Description>
<FieldError>...</FieldError>
</TextField>
```
- **TextField**：根容器，负责间距与状态管理
- **Label**：标签，必填时可显示星号（见 [Label](./label)）
- **Input**：带动画边框与背景的输入（见 [Input](./input)）
- **Description**：辅助说明文字（见 [Description](./description)）
- **FieldError**：校验错误展示（见 [FieldError](./field-error)）
## 用法
### 基础用法
提供带标签与说明的完整输入结构。
```tsx
<TextField>
<Label>邮箱</Label>
<Input placeholder="请输入邮箱" />
<Description>我们不会公开您的邮箱</Description>
</TextField>
```
### 必填
在必填字段的标签上显示星号。
```tsx
<TextField isRequired>
<Label>用户名</Label>
<Input placeholder="请选择用户名" />
</TextField>
```
### 校验
非法时展示错误信息。
```tsx
import { FieldError, Input, Label, TextField } from 'heroui-native';
<TextField isRequired isInvalid={true}>
<Label>邮箱</Label>
<Input placeholder="请输入邮箱" />
<FieldError>请输入有效邮箱</FieldError>
</TextField>;
```
### 局部覆盖非法状态
为单个部件覆盖上下文的非法状态。
```tsx
import {
Description,
FieldError,
Input,
Label,
TextField,
} from 'heroui-native';
<TextField isInvalid={true}>
<Label isInvalid={false}>邮箱</Label>
<Input placeholder="请输入邮箱" isInvalid={false} />
<Description isInvalid={false}>
尽管输入非法，此说明仍可显示
</Description>
<FieldError>邮箱格式不正确</FieldError>
</TextField>;
```
### 多行输入
用于较长内容。
```tsx
<TextField>
<Label>留言</Label>
<Input placeholder="请输入留言…" multiline numberOfLines={4} />
<Description>最多 500 字</Description>
</TextField>
```
### 禁用状态
禁用整个字段。
```tsx
<TextField isDisabled>
<Label>禁用字段</Label>
<Input placeholder="不可编辑" value="只读内容" />
</TextField>
```
### 变体
按场景切换输入样式。
```tsx
<TextField>
<Label>主要变体</Label>
<Input placeholder="主要样式" variant="primary" />
</TextField>
<TextField>
<Label>次要变体</Label>
<Input placeholder="次要样式" variant="secondary" />
</TextField>
```
### 自定义样式
通过 `className` 自定义输入外观。
```tsx
<TextField>
<Label>自定义样式</Label>
<Input
placeholder="自定义颜色"
className="bg-blue-50 border-blue-500 focus:border-blue-700"
/>
</TextField>
```
## 示例
```tsx
import { Ionicons } from '@expo/vector-icons';
import { Description, Input, Label, TextField } from 'heroui-native';
import { useState } from 'react';
import { Pressable, View } from 'react-native';
import { withUniwind } from 'uniwind';
const StyledIonicons = withUniwind(Ionicons);
export const TextInputContent = () => {
const [email, setEmail] = useState('');
const [password, setPassword] = useState('');
const [isPasswordVisible, setIsPasswordVisible] = useState(false);
return (
<View className="gap-4">
<TextField isRequired>
<Label>邮箱</Label>
<Input
placeholder="请输入邮箱"
keyboardType="email-address"
autoCapitalize="none"
value={email}
onChangeText={setEmail}
/>
<Description>
我们不会向他人公开您的邮箱。
</Description>
</TextField>
<TextField isRequired>
<Label>新密码</Label>
<View className="w-full flex-row items-center">
<Input
value={password}
onChangeText={setPassword}
className="flex-1 px-10"
placeholder="请输入密码"
secureTextEntry={!isPasswordVisible}
/>
<StyledIonicons
name="lock-closed-outline"
size={16}
className="absolute left-3.5 text-muted"
pointerEvents="none"
/>
<Pressable
className="absolute right-4"
onPress={() => setIsPasswordVisible(!isPasswordVisible)}
>
<StyledIonicons
name={isPasswordVisible ? 'eye-off-outline' : 'eye-outline'}
size={16}
className="text-muted"
/>
</Pressable>
</View>
<Description>密码至少 6 位</Description>
</TextField>
</View>
);
};
```
更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/text-field.tsx>)。
## API 参考
### TextField
| prop | type | default | description |
| ------------ | ---------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
| children | `React.ReactNode` | - | 文本字段内的子节点 |
| isDisabled | `boolean` | `false` | 是否禁用整个字段 |
| isInvalid | `boolean` | `false` | 是否处于非法状态 |
| isRequired | `boolean` | `false` | 是否必填（显示星号） |
| className | `string` | - | 根元素自定义 class |
| animation | `"disable-all" \| undefined` | `undefined` | 动画配置；`"disable-all"` 可禁用自身及子级的全部动画 |
| ...ViewProps | `ViewProps` | - | 支持 React Native `View` 的全部属性 |
> **说明**：`Label`、`Input`、`Description`、`FieldError` 的详细 API 见各自文档：
>
> - [Label](./label)
> - [Input](./input)
> - [Description](./description)
> - [FieldError](./field-error)
>
> 这些组件会通过 form-item-state 上下文自动消费 `TextField` 的表单状态。
## Hooks
### useTextField
访问 `TextField` 上下文，必须在 `TextField` 内使用。
```tsx
import { TextField, useTextField } from 'heroui-native';
function CustomComponent() {
const { isDisabled, isInvalid, isRequired } = useTextField();
// 使用上下文值…
}
```
#### 返回值
| property | type | description |
| ---------- | --------- | --------------------- |
| isDisabled | `boolean` | 是否禁用整个字段 |
| isInvalid | `boolean` | 是否处于非法状态 |
| isRequired | `boolean` | 是否必填 |
apps/docs/content/docs/cn/native/components/(layout)/card.mdx
+195
View File
@@ -0,0 +1,195 @@
---
title: Card 卡片
description: 卡片容器，提供灵活分区以结构化展示内容。
links:
source_native: card/card.tsx
styles_native: card/card.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/card-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/card-docs-dark.mp4"
/>
## 导入
```tsx
import { Card } from 'heroui-native';
```
## 结构
```tsx
<Card>
<Card.Header>...</Card.Header>
<Card.Body>
<Card.Title>...</Card.Title>
<Card.Description>...</Card.Description>
</Card.Body>
<Card.Footer>...</Card.Footer>
</Card>
```
- **Card**：主容器，继承 `Surface`；提供可配置的表面变体与整体布局。
- **Card.Header**：顶部区域，可放图标、徽章等。
- **Card.Body**：主内容区，`flex-1` 填充 `Header` 与 `Footer` 之间的空间。
- **Card.Title**：标题，前景色与中等字重。
- **Card.Description**：描述，弱化色与较小字号。
- **Card.Footer**：底部区域，可放按钮等操作。
## 用法
### 基础用法
使用内置分区组织内容。
```tsx
<Card>
<Card.Body>...</Card.Body>
</Card>
```
### 标题与描述
组合标题与描述以结构化展示文字。
```tsx
<Card>
<Card.Body>
<Card.Title>...</Card.Title>
<Card.Description>...</Card.Description>
</Card.Body>
</Card>
```
### 页头与页脚
增加顶部与底部区域放置图标、徽章或操作。
```tsx
<Card>
<Card.Header>...</Card.Header>
<Card.Body>...</Card.Body>
<Card.Footer>...</Card.Footer>
</Card>
```
### 变体
通过变体控制卡片背景外观。
```tsx
<Card variant="default">...</Card>
<Card variant="secondary">...</Card>
<Card variant="tertiary">...</Card>
<Card variant="transparent">...</Card>
```
### 横向布局
使用 `flex-row` 等样式创建横向卡片。
```tsx
<Card className="flex-row gap-4">
<Image source={...} className="size-24 rounded-lg" />
</Card>
```
### 背景图
使用绝对定位图片作为背景。
```tsx
<Card>
<Image source={...} className="absolute inset-0" />
<View className="gap-4">...</View>
</Card>
```
## 示例
```tsx
import { Button, Card } from 'heroui-native';
import { Ionicons } from '@expo/vector-icons';
import { View } from 'react-native';
export default function CardExample() {
return (
<Card>
<View className="gap-4">
<Card.Body className="mb-4">
<View className="gap-1 mb-2">
<Card.Title className="text-pink-500">¥450</Card.Title>
<Card.Title>客厅沙发 • 2025 系列</Card.Title>
</View>
<Card.Description>
这款沙发适合现代热带风、巴洛克灵感等空间。
</Card.Description>
</Card.Body>
<Card.Footer className="gap-3">
<Button variant="primary">立即购买</Button>
<Button variant="ghost">
<Button.Label>加入购物车</Button.Label>
<Ionicons name="bag-outline" size={16} />
</Button>
</Card.Footer>
</View>
</Card>
);
}
```
更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/card.tsx)。
## API 参考
### Card
| prop | type | default | description |
| -------------- | --------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 卡片内内容 |
| `variant` | `'default' \| 'secondary' \| 'tertiary' \| 'transparent'` | `'default'` | 卡片表面视觉变体 |
| `className` | `string` | - | 额外的 class |
| `animation` | `"disable-all" \| undefined` | `undefined` | 动画配置；`"disable-all"` 可禁用自身及子级的全部动画 |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部属性 |
### Card.Header
| prop | type | default | description |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | - | 页头内子节点 |
| `className` | `string` | - | 额外的 class |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部属性 |
### Card.Body
| prop | type | default | description |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | - | 主内容区子节点 |
| `className` | `string` | - | 额外的 class |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部属性 |
### Card.Footer
| prop | type | default | description |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | - | 页脚内子节点 |
| `className` | `string` | - | 额外的 class |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部属性 |
### Card.Title
| prop | type | default | description |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | - | 标题文字 |
| `className` | `string` | - | 额外的 class |
| `...TextProps` | `TextProps` | - | 支持 React Native `Text` 的全部属性 |
### Card.Description
| prop | type | default | description |
| -------------- | ----------------- | ------- | -------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 描述文字 |
| `className` | `string` | - | 额外的 class |
| `...TextProps` | `TextProps` | - | 支持 React Native `Text` 的全部属性 |
apps/docs/content/docs/cn/native/components/(layout)/separator.mdx
+116
View File
@@ -0,0 +1,116 @@
---
title: Separator 分隔符
description: 用于在视觉上分隔内容的简单线条。
links:
source_native: separator/separator.tsx
styles_native: separator/separator.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/separator-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/separator-docs-dark.mp4"
/>
## 导入
```tsx
import { Separator } from "heroui-native";
```
## 结构
```tsx
<Separator />
```
- **Separator**：简单的分隔线组件，可水平或垂直排列，并支持自定义粗细与变体样式。
## 用法
### 基础用法
在内容区块之间创建视觉分隔。
```tsx
<Separator />
```
### 方向
使用 `orientation` 控制分隔线方向。
```tsx
<View>
<Text>水平分隔线</Text>
<Separator orientation="horizontal" />
<Text>下方内容</Text>
</View>
<View className="h-24 flex-row">
<Text>左侧</Text>
<Separator orientation="vertical" />
<Text>右侧</Text>
</View>
```
### 变体
在细线与粗线之间选择，以强调程度区分。
```tsx
<Separator variant="thin" />
<Separator variant="thick" />
```
### 自定义粗细
使用数值精确控制线条粗细（像素）。
```tsx
<Separator thickness={1} />
<Separator thickness={5} />
<Separator thickness={10} />
```
## 示例
```tsx
import { Separator, Surface } from 'heroui-native';
import { Text, View } from 'react-native';
export default function SeparatorExample() {
return (
<Surface variant="secondary" className="px-6 py-7">
<Text className="text-base font-medium text-foreground">
HeroUI Native
</Text>
<Text className="text-sm text-muted">
现代化的 React Native 组件库。
</Text>
<Separator className="my-4" />
<View className="flex-row items-center h-5">
<Text className="text-sm text-foreground">组件</Text>
<Separator orientation="vertical" className="mx-3" />
<Text className="text-sm text-foreground">主题</Text>
<Separator orientation="vertical" className="mx-3" />
<Text className="text-sm text-foreground">示例</Text>
</View>
</Surface>
);
}
```
更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/separator.tsx)。
## API 参考
### Separator
| prop | type | default | description |
| -------------- | ---------------------------- | -------------- | -------------------------------------------------------------------------------------------- |
| `variant` | `'thin' \| 'thick'` | `'thin'` | 分隔线样式变体 |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | 分隔线方向 |
| `thickness` | `number` | `undefined` | 自定义粗细（像素）；水平时控制高度，垂直时控制宽度 |
| `className` | `string` | `undefined` | 额外的 class |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部属性 |
apps/docs/content/docs/cn/native/components/(layout)/surface.mdx
+146
View File
@@ -0,0 +1,146 @@
---
title: Surface 表面
description: 提供层级与背景样式的容器组件。
icon: updated
links:
source_native: surface/surface.tsx
styles_native: surface/surface.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/surface-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/surface-docs-dark.mp4"
/>
## 导入
```tsx
import { Surface } from 'heroui-native';
```
## 结构
Surface 是提供层级与背景样式的容器，可包裹子内容，并通过变体与样式属性定制外观。
```tsx
<Surface>...</Surface>
```
- **Surface**：主容器，通过变体提供一致的内边距、背景与层级感。
## 用法
### 基础用法
Surface 用于创建具有一致内边距与样式的容器。
```tsx
<Surface>...</Surface>
```
### 变体
通过不同层级控制视觉外观。
```tsx
<Surface variant="default">
...
</Surface>
<Surface variant="secondary">
...
</Surface>
<Surface variant="tertiary">
...
</Surface>
```
### 嵌套 Surface
使用不同变体嵌套，形成视觉层级。
```tsx
<Surface variant="default">
...
<Surface variant="secondary">
...
<Surface variant="tertiary">...</Surface>
</Surface>
</Surface>
```
### 自定义样式
通过 `className` 或 `style` 传入自定义样式。
```tsx
<Surface className="bg-accent-soft">
...
</Surface>
<Surface variant="tertiary" className="p-0">
...
</Surface>
```
### 禁用全部动画
将 `animation` 设为 `"disable-all"` 可禁用自身及子级的全部动画。
```tsx
{
/* 禁用自身及子级的全部动画 */
}
<Surface animation="disable-all">无动画</Surface>;
```
## 示例
```tsx
import { Surface } from 'heroui-native';
import { Text, View } from 'react-native';
export default function SurfaceExample() {
return (
<View className="gap-4">
<Surface variant="default" className="gap-2">
<AppText className="text-foreground">表面内容</AppText>
<AppText className="text-muted">
默认表面变体，使用 bg-surface 样式。
</AppText>
</Surface>
<Surface variant="secondary" className="gap-2">
<AppText className="text-foreground">表面内容</AppText>
<AppText className="text-muted">
次要表面变体，使用 bg-surface-secondary 样式。
</AppText>
</Surface>
<Surface variant="tertiary" className="gap-2">
<AppText className="text-foreground">表面内容</AppText>
<AppText className="text-muted">
第三级表面变体，使用 bg-surface-tertiary 样式。
</AppText>
</Surface>
</View>
);
}
```
更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/surface.tsx)。
## API 参考
### Surface
| prop | type | default | description |
| -------------- | --------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
| `variant` | `'default' \| 'secondary' \| 'tertiary' \| 'transparent'` | `'default'` | 视觉变体，控制背景色与边框 |
| `children` | `React.ReactNode` | - | 渲染在表面内的内容 |
| `className` | `string` | - | 额外的 class |
| `animation` | `"disable-all" \| undefined` | `undefined` | 动画配置；`"disable-all"` 可禁用自身及子级的全部动画 |
| `asChild` | `boolean` | `false` | 是否以子元素方式渲染 |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部属性 |
apps/docs/content/docs/cn/native/components/(media)/avatar.mdx
+396
View File
@@ -0,0 +1,396 @@
---
title: Avatar 头像
description: 展示用户头像，支持图片、文字首字母或回退图标。
links:
source_native: avatar/avatar.tsx
styles_native: avatar/avatar.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/avatar-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/avatar-docs-dark.mp4"
/>
## 导入
```tsx
import { Avatar } from 'heroui-native';
```
## 结构
```tsx
<Avatar>
<Avatar.Image />
<Avatar.Fallback />
</Avatar>
```
- **Avatar**：主容器，管理头像展示状态，向子组件提供尺寸与颜色上下文；可通过动画配置统一控制子级动画。
- **Avatar.Image**：可选图片组件，展示头像；自动处理加载与错误，并以不透明度淡入。
- **Avatar.Fallback**：图片加载失败或不可用时显示；无子节点时显示默认人像图标；支持可配置的进入动画与延迟。
## 用法
### 基础用法
未提供图片或文字时，显示默认人像图标。
```tsx
<Avatar>
<Avatar.Fallback />
</Avatar>
```
### 使用图片
展示头像图片并自动处理回退。
```tsx
<Avatar>
<Avatar.Image source={{ uri: 'https://example.com/avatar.jpg' }} />
<Avatar.Fallback>JD</Avatar.Fallback>
</Avatar>
```
### 文字首字母
使用首字母作为头像内容。
```tsx
<Avatar>
<Avatar.Fallback>AB</Avatar.Fallback>
</Avatar>
```
### 自定义图标
以自定义图标作为回退内容。
```tsx
<Avatar>
<Avatar.Fallback>
<Ionicons name="person" size={18} />
</Avatar.Fallback>
</Avatar>
```
### 尺寸
使用 `size` 控制头像大小。
```tsx
<Avatar size="sm">
<Avatar.Fallback />
</Avatar>
<Avatar size="md">
<Avatar.Fallback />
</Avatar>
<Avatar size="lg">
<Avatar.Fallback />
</Avatar>
```
### 变体
使用 `variant` 切换视觉风格。
```tsx
<Avatar variant="default">
<Avatar.Fallback>DF</Avatar.Fallback>
</Avatar>
<Avatar variant="soft">
<Avatar.Fallback>SF</Avatar.Fallback>
</Avatar>
```
### 颜色
应用不同颜色变体。
```tsx
<Avatar color="default">
<Avatar.Fallback>DF</Avatar.Fallback>
</Avatar>
<Avatar color="accent">
<Avatar.Fallback>AC</Avatar.Fallback>
</Avatar>
<Avatar color="success">
<Avatar.Fallback>SC</Avatar.Fallback>
</Avatar>
<Avatar color="warning">
<Avatar.Fallback>WR</Avatar.Fallback>
</Avatar>
<Avatar color="danger">
<Avatar.Fallback>DG</Avatar.Fallback>
</Avatar>
```
### 延迟显示回退
延迟显示回退，避免图片加载时的闪烁。
```tsx
<Avatar>
<Avatar.Image source={{ uri: imageUrl }} />
<Avatar.Fallback delayMs={600}>NA</Avatar.Fallback>
</Avatar>
```
### 自定义图片组件
配合 `asChild` 使用自定义图片组件。
```tsx
import { Image } from 'expo-image';
<Avatar>
<Avatar.Image source={{ uri: imageUrl }} asChild>
<Image style={{ width: '100%', height: '100%' }} contentFit="cover" />
</Avatar.Image>
<Avatar.Fallback>EI</Avatar.Fallback>
</Avatar>;
```
### 动画控制
在 Avatar 不同层级控制动画。
#### 禁用全部动画
在根组件禁用自身及子级的全部动画：
```tsx
<Avatar animation="disable-all">
<Avatar.Image source={{ uri: imageUrl }} />
<Avatar.Fallback>JD</Avatar.Fallback>
</Avatar>
```
#### 自定义图片动画
自定义图片不透明度动画：
```tsx
<Avatar>
<Avatar.Image
source={{ uri: imageUrl }}
animation={{
opacity: {
value: [0.3, 1],
timingConfig: { duration: 300 },
},
}}
/>
<Avatar.Fallback>JD</Avatar.Fallback>
</Avatar>
```
#### 自定义回退动画
自定义回退进入动画：
```tsx
import { FadeInDown } from 'react-native-reanimated';
<Avatar>
<Avatar.Image source={{ uri: imageUrl }} />
<Avatar.Fallback
animation={{
entering: {
value: FadeInDown.duration(400),
},
}}
>
JD
</Avatar.Fallback>
</Avatar>;
```
#### 单独禁用动画
对指定子组件禁用动画：
```tsx
<Avatar>
<Avatar.Image source={{ uri: imageUrl }} animation={false} />
<Avatar.Fallback animation="disabled">JD</Avatar.Fallback>
</Avatar>
```
## 示例
```tsx
import { Avatar } from 'heroui-native';
import { View } from 'react-native';
export default function AvatarExample() {
const users = [
{ id: 1, image: 'https://example.com/user1.jpg', name: '张 三' },
{ id: 2, image: 'https://example.com/user2.jpg', name: '李 四' },
{ id: 3, image: 'https://example.com/user3.jpg', name: '王 五' },
];
return (
<View className="flex-row gap-4">
{users.map((user) => (
<Avatar key={user.id} size="lg" color="accent">
<Avatar.Image source={{ uri: user.image }} />
<Avatar.Fallback>
{user.name
.split(' ')
.map((n) => n[0])
.join('')}
</Avatar.Fallback>
</Avatar>
))}
</View>
);
}
```
更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/avatar.tsx)。
## API 参考
### Avatar
| prop | type | default | description |
| -------------- | ------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 头像内容（`Image` 与/或 `Fallback`） |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 尺寸 |
| `variant` | `'default' \| 'soft'` | `'default'` | 视觉变体 |
| `color` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'accent'` | 颜色变体 |
| `className` | `string` | - | 额外的 class |
| `animation` | `"disable-all"` \| `undefined` | `undefined` | 动画配置；`"disable-all"` 可禁用自身及子级的全部动画 |
| `alt` | `string` | - | 无障碍替代文本描述 |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部属性 |
### Avatar.Image
根据 `asChild` 扩展不同的基础类型：
- `asChild={false}`（默认）：扩展自 React Native Reanimated 的 `AnimatedProps<ImageProps>`
- `asChild={true}`：扩展自定义图片组件的原语图片属性
**说明：** `asChild={true}` 时，取决于自定义组件实现，`className` 可能不会生效；请确保自定义组件正确处理样式 props。
| prop | type | default | description |
| ----------------------- | ---------------------------------------------- | ------- | ------------------------------------------------------------ |
| `source` | `ImageSourcePropType` | - | 图片源（`asChild={false}` 时必填） |
| `asChild` | `boolean` | `false` | 是否使用自定义图片子组件 |
| `className` | `string` | - | 额外的 class |
| `animation` | `AvatarImageAnimation` | - | 动画配置 |
| `isAnimatedStyleActive` | `boolean` | `true` | 是否启用 Reanimated 动画样式 |
| `...AnimatedProps` | `AnimatedProps<ImageProps>` or primitive props | - | 随 `asChild` 变化的额外属性 |
#### AvatarImageAnimation
图片动画配置，可为：
- `false` 或 `"disabled"`：禁用全部动画
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| ---------------------- | ----------------------- | --------------------------------------------------- | ------------------------------------ |
| `state` | `'disabled' \| boolean` | - | 在自定义属性时禁用动画 |
| `opacity.value` | `[number, number]` | `[0, 1]` | 不透明度 [初始, 已加载] |
| `opacity.timingConfig` | `WithTimingConfig` | `{ duration: 200, easing: Easing.in(Easing.ease) }` | 时间曲线配置 |
**说明：** `asChild={true}` 时动画会自动禁用。
### Avatar.Fallback
| prop | type | default | description |
| ----------------------- | ------------------------------------------------------------- | --------------------- | --------------------------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 回退内容（文字、图标或自定义节点） |
| `delayMs` | `number` | `0` | 显示回退前的延迟（毫秒），作用于进入动画 |
| `color` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | inherited from parent | 回退颜色变体 |
| `className` | `string` | - | 容器额外 class |
| `classNames` | `ElementSlots<AvatarFallbackSlots>` | - | 各部分额外 class |
| `styles` | `{ container?: ViewStyle; text?: TextStyle }` | - | 回退各部分的样式 |
| `textProps` | `TextProps` | - | 子节点为字符串时传给 `Text` 的属性 |
| `iconProps` | `PersonIconProps` | - | 自定义默认人像图标的属性 |
| `animation` | `AvatarFallbackAnimation` | - | 动画配置 |
| `...Animated.ViewProps` | `Animated.ViewProps` | - | 支持 Reanimated `Animated.View` 的全部属性 |
**classNames：** `ElementSlots<AvatarFallbackSlots>` 提供类型安全的 class。可用插槽：`container`、`text`。
#### `styles`
| prop | type | description |
| ----------- | ----------- | ----------- |
| `container` | `ViewStyle` | 容器样式 |
| `text` | `TextStyle` | 文字样式 |
#### AvatarFallbackAnimation
回退动画配置，可为：
- `false` 或 `"disabled"`：禁用全部动画
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| ---------------- | ----------------------- | ----------------------------------------------------------------------------------- | ------------------------ |
| `state` | `'disabled' \| boolean` | - | 在自定义属性时禁用动画 |
| `entering.value` | `EntryOrExitLayoutType` | `FadeIn`<br/>`.duration(200)`<br/>`.easing(Easing.in(Easing.ease))`<br/>`.delay(0)` | 自定义进入动画 |
#### PersonIconProps
| prop | type | description |
| ------- | -------- | ---------------- |
| `size` | `number` | 图标尺寸（可选） |
| `color` | `string` | 图标颜色（可选） |
## Hooks
### useAvatar
访问 Avatar 根上下文，获取头像状态。
**说明：** `status` 常用于在图片加载时显示骨架屏。
```tsx
import { Avatar, useAvatar, Skeleton } from 'heroui-native';
function AvatarWithSkeleton() {
return (
<Avatar>
<Avatar.Image source={{ uri: imageUrl }} />
<AvatarContent />
<Avatar.Fallback>JD</Avatar.Fallback>
</Avatar>
);
}
function AvatarContent() {
const { status } = useAvatar();
if (status === 'loading') {
return <Skeleton className="absolute inset-0 rounded-full" />;
}
return null;
}
```
| property | type | description |
| ----------- | ---------------------------------------------------- | ------------------------------------ |
| `status` | `'loading' \| 'loaded' \| 'error'` | 当前图片加载状态 |
| `setStatus` | `(status: 'loading' \| 'loaded' \| 'error') => void` | 手动设置状态（高级用法） |
**状态含义：**
- `'loading'`：图片加载中，可显示骨架屏
- `'loaded'`：图片加载成功
- `'error'`：加载失败或资源无效，会自动显示回退
apps/docs/content/docs/cn/native/components/(navigation)/accordion.mdx
+447
View File
@@ -0,0 +1,447 @@
---
title: Accordion 手风琴
description: 可折叠内容面板，在紧凑空间内组织信息
links:
source_native: accordion/accordion.tsx
styles_native: accordion/accordion.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/accordion-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/accordion-docs-dark-1.mp4"
/>
## 导入
```tsx
import { Accordion } from 'heroui-native';
```
## 结构
```tsx
<Accordion>
<Accordion.Item>
<Accordion.Trigger>
...
<Accordion.Indicator>...</Accordion.Indicator>
</Accordion.Trigger>
<Accordion.Content>...</Accordion.Content>
</Accordion.Item>
</Accordion>
```
- **Accordion**：主容器，管理手风琴状态与行为；控制各条目的展开/收起，支持单选或多选展开模式，并提供 `default` 或 `surface` 等视觉变体。
- **Accordion.Item**：单个条目的容器，包裹触发器与内容，并管理该条目的展开状态。
- **Accordion.Trigger**：用于切换条目展开的可交互区域，基于 Header 与 Trigger 原语构建。
- **Accordion.Indicator**：可选的视觉指示器，展示展开状态；默认使用随状态旋转的动画 chevron 图标。
- **Accordion.Content**：可展开内容的容器，配合布局过渡动画实现平滑展开/收起。
## 用法
### 基础用法
Accordion 通过复合子组件创建可展开的内容区块。
```tsx
<Accordion selectionMode="single">
<Accordion.Item value="1">
<Accordion.Trigger>
...
<Accordion.Indicator />
</Accordion.Trigger>
<Accordion.Content>...</Accordion.Content>
</Accordion.Item>
</Accordion>
```
### 单选模式
同一时间只允许展开一个条目。
```tsx
<Accordion selectionMode="single" defaultValue="2">
<Accordion.Item value="1">
<Accordion.Trigger>...</Accordion.Trigger>
<Accordion.Content>...</Accordion.Content>
</Accordion.Item>
<Accordion.Item value="2">
<Accordion.Trigger>...</Accordion.Trigger>
<Accordion.Content>...</Accordion.Content>
</Accordion.Item>
</Accordion>
```
### 多选模式
允许多个条目同时展开。
```tsx
<Accordion selectionMode="multiple" defaultValue={['1', '3']}>
<Accordion.Item value="1">
<Accordion.Trigger>...</Accordion.Trigger>
<Accordion.Content>...</Accordion.Content>
</Accordion.Item>
<Accordion.Item value="2">
<Accordion.Trigger>...</Accordion.Trigger>
<Accordion.Content>...</Accordion.Content>
</Accordion.Item>
<Accordion.Item value="3">
<Accordion.Trigger>...</Accordion.Trigger>
<Accordion.Content>...</Accordion.Content>
</Accordion.Item>
</Accordion>
```
### Surface 变体
为手风琴应用表面容器样式。
```tsx
<Accordion selectionMode="single" variant="surface">
<Accordion.Item value="1">
<Accordion.Trigger>
...
<Accordion.Indicator />
</Accordion.Trigger>
<Accordion.Content>...</Accordion.Content>
</Accordion.Item>
</Accordion>
```
### 自定义指示器
用自定义内容替换默认 chevron 指示器。
```tsx
<Accordion selectionMode="single">
<Accordion.Item value="1">
<Accordion.Trigger>
...
<Accordion.Indicator>
<CustomIndicator />
</Accordion.Indicator>
</Accordion.Trigger>
<Accordion.Content>...</Accordion.Content>
</Accordion.Item>
</Accordion>
```
### 无分隔线
隐藏条目之间的分隔线。
```tsx
<Accordion selectionMode="single" hideSeparator>
<Accordion.Item value="1">
<Accordion.Trigger>...</Accordion.Trigger>
<Accordion.Content>...</Accordion.Content>
</Accordion.Item>
<Accordion.Item value="2">
<Accordion.Trigger>...</Accordion.Trigger>
<Accordion.Content>...</Accordion.Content>
</Accordion.Item>
</Accordion>
```
### 自定义样式
通过 `className`、`classNames` 或 `styles` 传入自定义样式。
```tsx
<Accordion
className="rounded-lg"
classNames={{
container: 'bg-surface',
separator: 'bg-separator/50',
}}
styles={{
container: { padding: 16 },
separator: { height: 2 },
}}
>
<Accordion.Item value="1">
<Accordion.Trigger>...</Accordion.Trigger>
<Accordion.Content>...</Accordion.Content>
</Accordion.Item>
</Accordion>
```
### 配合 PressableFeedback
对 `Accordion.Trigger` 使用 `asChild`，并用 `PressableFeedback` 包裹内容以添加按压反馈动画。
```tsx
import { Accordion, PressableFeedback } from 'heroui-native';
import { View } from 'react-native';
<Accordion>
<Accordion.Item value="1">
<Accordion.Trigger asChild>
<PressableFeedback animation={{ scale: false }}>
<PressableFeedback.Scale className="flex-row items-center flex-1 gap-3">
<Text>条目标题</Text>
</PressableFeedback.Scale>
<Accordion.Indicator />
<PressableFeedback.Highlight
animation={{ opacity: { value: [0, 0.05] } }}
/>
</PressableFeedback>
</Accordion.Trigger>
<Accordion.Content>...</Accordion.Content>
</Accordion.Item>
</Accordion>;
```
## 示例
```tsx
import { Accordion, useThemeColor } from 'heroui-native';
import { Ionicons } from '@expo/vector-icons';
import { View, Text } from 'react-native';
export default function AccordionExample() {
const themeColorMuted = useThemeColor('muted');
const accordionData = [
{
id: '1',
title: '如何下单？',
icon: <Ionicons name="bag-outline" size={16} color={themeColorMuted} />,
content:
'这是一段示例说明文字，用于演示折叠面板中的正文内容展示效果。',
},
{
id: '2',
title: '支持哪些支付方式？',
icon: <Ionicons name="card-outline" size={16} color={themeColorMuted} />,
content:
'这是一段示例说明文字，用于演示折叠面板中的正文内容展示效果。',
},
{
id: '3',
title: '运费如何计算？',
icon: <Ionicons name="cube-outline" size={16} color={themeColorMuted} />,
content:
'这是一段示例说明文字，用于演示折叠面板中的正文内容展示效果。',
},
];
return (
<Accordion selectionMode="single" variant="surface" defaultValue="2">
{accordionData.map((item) => (
<Accordion.Item key={item.id} value={item.id}>
<Accordion.Trigger>
<View className="flex-row items-center flex-1 gap-3">
{item.icon}
<Text className="text-foreground text-base flex-1">
{item.title}
</Text>
</View>
<Accordion.Indicator />
</Accordion.Trigger>
<Accordion.Content>
<Text className="text-muted text-base/relaxed px-[25px]">
{item.content}
</Text>
</Accordion.Content>
</Accordion.Item>
))}
</Accordion>
);
}
```
更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/accordion.tsx)。
## API 参考
### Accordion
| prop | type | default | description |
| ----------------------- | -------------------------------------------------- | ----------- | -------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 渲染在手风琴内的子节点 |
| `selectionMode` | `'single' \| 'multiple'` | - | 允许单条或多条同时展开 |
| `variant` | `'default' \| 'surface'` | `'default'` | 手风琴视觉变体 |
| `hideSeparator` | `boolean` | `false` | 是否隐藏条目之间的分隔线 |
| `defaultValue` | `string \| string[] \| undefined` | - | 非受控模式下的默认展开项 |
| `value` | `string \| string[] \| undefined` | - | 受控模式下的当前展开项 |
| `isDisabled` | `boolean` | - | 是否禁用全部条目 |
| `isCollapsible` | `boolean` | `true` | 已展开条目是否可再次收起 |
| `animation` | `AccordionRootAnimation` | - | 根级动画配置 |
| `className` | `string` | - | 容器的额外 class |
| `classNames` | `ElementSlots<RootSlots>` | - | 各插槽的额外 class |
| `styles` | `Partial<Record<RootSlots, ViewStyle>>` | - | 根组件各部分的样式 |
| `onValueChange` | `(value: string \| string[] \| undefined) => void` | - | 展开项变化时的回调 |
| `...Animated.ViewProps` | `Animated.ViewProps` | - | 支持 Reanimated `Animated.View` 的全部属性 |
#### `ElementSlots<RootSlots>`
| prop | type | description |
| ----------- | -------- | ----------------------------------- |
| `container` | `string` | 手风琴容器的自定义 class |
| `separator` | `string` | 条目之间分隔线的自定义 class |
#### `styles`
| prop | type | description |
| ----------- | ----------- | ---------------------- |
| `container` | `ViewStyle` | 手风琴容器样式 |
| `separator` | `ViewStyle` | 条目之间分隔线样式 |
#### AccordionRootAnimation
手风琴根组件的动画配置，可为：
- `false` 或 `"disabled"`：仅禁用根级动画
- `"disable-all"`：禁用全部动画（含子级）
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| -------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------- |
| `state` | `'disabled' \| 'disable-all' \| boolean` | - | 在自定义属性时禁用动画 |
| `layout.value` | `LayoutTransition` | `LinearTransition`<br/>`.springify()`<br/>`.damping(140)`<br/>`.stiffness(1600)`<br/>`.mass(4)` | 手风琴过渡的自定义布局动画 |
### Accordion.Item
| prop | type | default | description |
| ----------------------- | --------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------- |
| `children` | `React.ReactNode \| ((props: AccordionItemRenderProps) => React.ReactNode)` | - | 条目内的子节点，或渲染函数 |
| `value` | `string` | - | 唯一标识该条目的值 |
| `isDisabled` | `boolean` | - | 是否禁用该条目 |
| `className` | `string` | - | 额外的 class |
| `...Animated.ViewProps` | `Animated.ViewProps` | - | 支持 Reanimated `Animated.View` 的全部属性 |
#### AccordionItemRenderProps
| prop | type | description |
| ------------ | --------- | ------------------------ |
| `isExpanded` | `boolean` | 当前条目是否展开 |
| `value` | `string` | 该条目的唯一值 |
### Accordion.Trigger
| prop | type | default | description |
| ------------------- | ----------------- | ------- | ------------------------------------ |
| `children` | `React.ReactNode` | - | 触发器内的子节点 |
| `className` | `string` | - | 额外的 class |
| `isDisabled` | `boolean` | - | 是否禁用触发器 |
| `...PressableProps` | `PressableProps` | - | 支持 React Native `Pressable` 的属性 |
### Accordion.Indicator
| prop | type | default | description |
| ----------------------- | ----------------------------- | ------- | -------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 自定义指示器内容；未提供时默认为带动画的 chevron |
| `className` | `string` | - | 额外的 class |
| `iconProps` | `AccordionIndicatorIconProps` | - | 图标配置 |
| `animation` | `AccordionIndicatorAnimation` | - | 指示器动画配置 |
| `isAnimatedStyleActive` | `boolean` | `true` | 是否启用 Reanimated 动画样式 |
| `...Animated.ViewProps` | `Animated.ViewProps` | - | 支持 Reanimated `Animated.View` 的全部属性 |
#### AccordionIndicatorIconProps
| prop | type | default | description |
| ------- | -------- | ------------ | ----------- |
| `size` | `number` | `16` | 图标尺寸 |
| `color` | `string` | `foreground` | 图标颜色 |
#### AccordionIndicatorAnimation
指示器动画配置，可为：
- `false` 或 `"disabled"`：禁用全部动画
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| ----------------------- | ----------------------- | -------------------------------------------- | ------------------------------------------------ |
| `state` | `'disabled' \| boolean` | - | 在自定义属性时禁用动画 |
| `rotation.value` | `[number, number]` | `[0, -180]` | 旋转角度 [收起, 展开]，单位为度 |
| `rotation.springConfig` | `WithSpringConfig` | `{ damping: 140, stiffness: 1000, mass: 4 }` | 旋转弹簧动画配置 |
### Accordion.Content
| prop | type | default | description |
| -------------- | --------------------------- | ------- | ---------------------------------- |
| `children` | `React.ReactNode` | - | 内容区域内的子节点 |
| `className` | `string` | - | 额外的 class |
| `animation` | `AccordionContentAnimation` | - | 内容动画配置 |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的属性 |
#### AccordionContentAnimation
内容区动画配置，可为：
- `false` 或 `"disabled"`：禁用全部动画
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| ---------------- | ----------------------- | -------------------------------------------------------------------- | ------------------------ |
| `state` | `'disabled' \| boolean` | - | 在自定义属性时禁用动画 |
| `entering.value` | `EntryOrExitLayoutType` | `FadeIn`<br/>`.duration(200)`<br/>`.easing(Easing.out(Easing.ease))` | 自定义进入动画 |
| `exiting.value` | `EntryOrExitLayoutType` | `FadeOut`<br/>`.duration(200)`<br/>`.easing(Easing.in(Easing.ease))` | 自定义退出动画 |
## Hooks
### useAccordion
访问手风琴根上下文，必须在 `Accordion` 内使用。
```tsx
import { useAccordion } from 'heroui-native';
const { value, onValueChange, selectionMode, isCollapsible, isDisabled } =
useAccordion();
```
#### 返回值
| property | type | description |
| --------------- | --------------------------------------------------------------------- | ------------------------------------------------ |
| `selectionMode` | `'single' \| 'multiple' \| undefined` | 单选或多选展开模式 |
| `value` | `(string \| undefined) \| string[]` | 当前展开项：单选为字符串，多选为数组 |
| `onValueChange` | `(value: string \| undefined) => void \| ((value: string[]) => void)` | 更新展开项的回调 |
| `isCollapsible` | `boolean` | 已展开项是否可收起 |
| `isDisabled` | `boolean \| undefined` | 是否禁用全部条目 |
### useAccordionItem
访问单条条目上下文，必须在 `Accordion.Item` 内使用。
```tsx
import { useAccordionItem } from 'heroui-native';
const { value, isExpanded, isDisabled, nativeID } = useAccordionItem();
```
#### 返回值
| property | type | description |
| ------------ | ---------------------- | ------------------------------------ |
| `value` | `string` | 该条目的唯一值 |
| `isExpanded` | `boolean` | 当前是否展开 |
| `isDisabled` | `boolean \| undefined` | 该条目是否禁用 |
| `nativeID` | `string` | 无障碍与 ARIA 使用的原生 ID |
## 特别说明
当 Accordion 与同屏其他组件一起使用时，请为这些组件导入并应用 `AccordionLayoutTransition`，以保证整屏布局动画一致、顺滑。
```jsx
import { Accordion, AccordionLayoutTransition } from 'heroui-native';
import Animated from 'react-native-reanimated';
<Animated.ScrollView layout={AccordionLayoutTransition}>
<Animated.View layout={AccordionLayoutTransition}>
{/* 其他内容 */}
</Animated.View>
<Accordion>{/* 手风琴条目 */}</Accordion>
</Animated.ScrollView>;
```
这样在展开或收起时，屏幕上各组件会使用相同的时长与缓动，体验更统一。
apps/docs/content/docs/cn/native/components/(navigation)/list-group.mdx
+397
View File
@@ -0,0 +1,397 @@
---
title: ListGroup 列表组
description: 基于 Surface 的容器，用于分组展示列表项并保持一致的布局与间距。
links:
source_native: list-group/list-group.tsx
styles_native: list-group/list-group.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/list-group-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/list-group-docs-dark.mp4"
/>
## 导入
```tsx
import { ListGroup } from 'heroui-native';
```
## 结构
```tsx
<ListGroup>
<ListGroup.Item>
<ListGroup.ItemPrefix>...</ListGroup.ItemPrefix>
<ListGroup.ItemContent>
<ListGroup.ItemTitle>...</ListGroup.ItemTitle>
<ListGroup.ItemDescription>...</ListGroup.ItemDescription>
</ListGroup.ItemContent>
<ListGroup.ItemSuffix />
</ListGroup.Item>
</ListGroup>
```
- **ListGroup**：基于 Surface 的根容器，用于分组列表项；支持全部 Surface 变体（`default`、`secondary`、`tertiary`、`transparent`）。
- **ListGroup.Item**：可按压的水平 `flex-row` 行容器，提供统一的间距与对齐。
- **ListGroup.ItemPrefix**：可选前导槽，用于图标、头像等。
- **ListGroup.ItemContent**：`flex-1` 包裹标题与说明，占据剩余横向空间。
- **ListGroup.ItemTitle**：主标题，前景色与中等字重。
- **ListGroup.ItemDescription**：次要说明，弱化颜色与较小字号。
- **ListGroup.ItemSuffix**：可选尾部槽；默认渲染右箭头；传入子节点可覆盖默认图标。
## 用法
### 基础用法
通过组合子部件创建带标题与说明的分组列表。
```tsx
<ListGroup>
<ListGroup.Item>
<ListGroup.ItemContent>
<ListGroup.ItemTitle>个人信息</ListGroup.ItemTitle>
<ListGroup.ItemDescription>
姓名、邮箱、手机号
</ListGroup.ItemDescription>
</ListGroup.ItemContent>
<ListGroup.ItemSuffix />
</ListGroup.Item>
<Separator className="mx-4" />
<ListGroup.Item>
<ListGroup.ItemContent>
<ListGroup.ItemTitle>支付方式</ListGroup.ItemTitle>
<ListGroup.ItemDescription>
Visa 尾号 4829
</ListGroup.ItemDescription>
</ListGroup.ItemContent>
<ListGroup.ItemSuffix />
</ListGroup.Item>
</ListGroup>
```
### 带图标
使用 `ListGroup.ItemPrefix` 放置前置图标。
```tsx
<ListGroup>
<ListGroup.Item>
<ListGroup.ItemPrefix>
<Icon name="person-outline" size={22} />
</ListGroup.ItemPrefix>
<ListGroup.ItemContent>
<ListGroup.ItemTitle>个人资料</ListGroup.ItemTitle>
<ListGroup.ItemDescription>
姓名、照片、简介
</ListGroup.ItemDescription>
</ListGroup.ItemContent>
<ListGroup.ItemSuffix />
</ListGroup.Item>
<Separator className="mx-4" />
<ListGroup.Item>
<ListGroup.ItemPrefix>
<Icon name="lock-closed-outline" size={22} />
</ListGroup.ItemPrefix>
<ListGroup.ItemContent>
<ListGroup.ItemTitle>安全</ListGroup.ItemTitle>
<ListGroup.ItemDescription>
密码、双重验证
</ListGroup.ItemDescription>
</ListGroup.ItemContent>
<ListGroup.ItemSuffix />
</ListGroup.Item>
</ListGroup>
```
### 仅标题
省略 `ListGroup.ItemDescription` 以展示仅标题行。
```tsx
<ListGroup>
<ListGroup.Item>
<ListGroup.ItemPrefix>
<Icon name="wifi-outline" size={22} />
</ListGroup.ItemPrefix>
<ListGroup.ItemContent>
<ListGroup.ItemTitle>Wi-Fi</ListGroup.ItemTitle>
</ListGroup.ItemContent>
<ListGroup.ItemSuffix />
</ListGroup.Item>
<Separator className="mx-4" />
<ListGroup.Item>
<ListGroup.ItemPrefix>
<Icon name="bluetooth-outline" size={22} />
</ListGroup.ItemPrefix>
<ListGroup.ItemContent>
<ListGroup.ItemTitle>蓝牙</ListGroup.ItemTitle>
</ListGroup.ItemContent>
<ListGroup.ItemSuffix />
</ListGroup.Item>
</ListGroup>
```
### Surface 变体
为根容器应用不同的视觉变体。
```tsx
<ListGroup variant="transparent">
<ListGroup.Item>
<ListGroup.ItemContent>
<ListGroup.ItemTitle>Wi-Fi</ListGroup.ItemTitle>
</ListGroup.ItemContent>
<ListGroup.ItemSuffix />
</ListGroup.Item>
</ListGroup>
```
### 自定义尾部
向 `ListGroup.ItemSuffix` 传入子节点以覆盖默认箭头。
```tsx
<ListGroup>
<ListGroup.Item>
<ListGroup.ItemContent>
<ListGroup.ItemTitle>语言</ListGroup.ItemTitle>
<ListGroup.ItemDescription>简体中文</ListGroup.ItemDescription>
</ListGroup.ItemContent>
<ListGroup.ItemSuffix>
<Icon name="arrow-forward" size={18} />
</ListGroup.ItemSuffix>
</ListGroup.Item>
<Separator className="mx-4" />
<ListGroup.Item>
<ListGroup.ItemContent>
<ListGroup.ItemTitle>通知</ListGroup.ItemTitle>
</ListGroup.ItemContent>
<ListGroup.ItemSuffix>
<Chip variant="primary" color="danger">
<Chip.Label className="font-bold">7</Chip.Label>
</Chip>
</ListGroup.ItemSuffix>
</ListGroup.Item>
</ListGroup>
```
### 自定义尾部图标属性
通过 `iconProps` 调整默认箭头尺寸与颜色。
```tsx
<ListGroup>
<ListGroup.Item>
<ListGroup.ItemContent>
<ListGroup.ItemTitle>存储空间</ListGroup.ItemTitle>
<ListGroup.ItemDescription>
已用 12.4 GB / 共 50 GB
</ListGroup.ItemDescription>
</ListGroup.ItemContent>
<ListGroup.ItemSuffix iconProps={{ size: 18, color: mutedColor }} />
</ListGroup.Item>
</ListGroup>
```
### 配合 PressableFeedback
用 `PressableFeedback` 包裹列表项以添加缩放与水波纹反馈。此模式下将 `onPress` 放在 `PressableFeedback` 上，并对 `ListGroup.Item` 使用 `disabled`。
```tsx
import { ListGroup, PressableFeedback, Separator } from 'heroui-native';
<ListGroup>
<PressableFeedback animation={false} onPress={() => {}}>
<PressableFeedback.Scale>
<ListGroup.Item disabled>
<ListGroup.ItemContent>
<ListGroup.ItemTitle>外观</ListGroup.ItemTitle>
<ListGroup.ItemDescription>
主题、字号、显示
</ListGroup.ItemDescription>
</ListGroup.ItemContent>
<ListGroup.ItemSuffix />
</ListGroup.Item>
</PressableFeedback.Scale>
<PressableFeedback.Ripple />
</PressableFeedback>
<Separator className="mx-4" />
<PressableFeedback animation={false} onPress={() => {}}>
<PressableFeedback.Scale>
<ListGroup.Item disabled>
<ListGroup.ItemContent>
<ListGroup.ItemTitle>通知</ListGroup.ItemTitle>
<ListGroup.ItemDescription>
提醒、声音、角标
</ListGroup.ItemDescription>
</ListGroup.ItemContent>
<ListGroup.ItemSuffix />
</ListGroup.Item>
</PressableFeedback.Scale>
<PressableFeedback.Ripple />
</PressableFeedback>
</ListGroup>
```
## 示例
```tsx
import { Ionicons } from '@expo/vector-icons';
import { ListGroup, Separator, useThemeColor } from 'heroui-native';
import { View, Text } from 'react-native';
import { withUniwind } from 'uniwind';
const StyledIonicons = withUniwind(Ionicons);
export default function ListGroupExample() {
const mutedColor = useThemeColor('muted');
return (
<View className="flex-1 justify-center px-5">
<Text className="text-sm text-muted mb-2 ml-2">账户</Text>
<ListGroup className="mb-6">
<ListGroup.Item>
<ListGroup.ItemPrefix>
<StyledIonicons
name="person-outline"
size={22}
className="text-foreground"
/>
</ListGroup.ItemPrefix>
<ListGroup.ItemContent>
<ListGroup.ItemTitle>个人信息</ListGroup.ItemTitle>
<ListGroup.ItemDescription>
姓名、邮箱、手机号
</ListGroup.ItemDescription>
</ListGroup.ItemContent>
<ListGroup.ItemSuffix />
</ListGroup.Item>
<Separator className="mx-4" />
<ListGroup.Item>
<ListGroup.ItemPrefix>
<StyledIonicons
name="card-outline"
size={22}
className="text-foreground"
/>
</ListGroup.ItemPrefix>
<ListGroup.ItemContent>
<ListGroup.ItemTitle>支付方式</ListGroup.ItemTitle>
<ListGroup.ItemDescription>
Visa 尾号 4829
</ListGroup.ItemDescription>
</ListGroup.ItemContent>
<ListGroup.ItemSuffix />
</ListGroup.Item>
</ListGroup>
<Text className="text-sm text-muted mb-2 ml-2">偏好设置</Text>
<ListGroup>
<ListGroup.Item>
<ListGroup.ItemPrefix>
<StyledIonicons
name="color-palette-outline"
size={22}
className="text-foreground"
/>
</ListGroup.ItemPrefix>
<ListGroup.ItemContent>
<ListGroup.ItemTitle>外观</ListGroup.ItemTitle>
<ListGroup.ItemDescription>
主题、字号、显示
</ListGroup.ItemDescription>
</ListGroup.ItemContent>
<ListGroup.ItemSuffix />
</ListGroup.Item>
<Separator className="mx-4" />
<ListGroup.Item>
<ListGroup.ItemPrefix>
<StyledIonicons
name="notifications-outline"
size={22}
className="text-foreground"
/>
</ListGroup.ItemPrefix>
<ListGroup.ItemContent>
<ListGroup.ItemTitle>通知</ListGroup.ItemTitle>
<ListGroup.ItemDescription>
提醒、声音、角标
</ListGroup.ItemDescription>
</ListGroup.ItemContent>
<ListGroup.ItemSuffix iconProps={{ size: 18, color: mutedColor }} />
</ListGroup.Item>
</ListGroup>
</View>
);
}
```
更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/list-group.tsx)。
## API 参考
### ListGroup
| prop | type | default | description |
| -------------- | ---------------------------------------------------------- | ----------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | - | 分组内的子节点 |
| `variant` | `'default' \| 'secondary' \| 'tertiary' \| 'transparent'` | `'default'` | 底层 Surface 容器的视觉变体 |
| `className` | `string` | - | 根容器额外 class |
| `...ViewProps` | `ViewProps` | - | 支持全部标准 React Native `View` 属性 |
### ListGroup.Item
| prop | type | default | description |
| ------------------- | ----------------- | ------- | ------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 列表行内的子节点 |
| `className` | `string` | - | 列表行额外 class |
| `...PressableProps` | `PressableProps` | - | 支持全部标准 React Native `Pressable` 属性 |
### ListGroup.ItemPrefix
| prop | type | default | description |
| -------------- | ----------------- | ------- | ------------------------------------------------------ |
| `children` | `React.ReactNode` | - | 前导内容，如图标或头像 |
| `className` | `string` | - | 前导区域额外 class |
| `...ViewProps` | `ViewProps` | - | 支持全部标准 React Native `View` 属性 |
### ListGroup.ItemContent
| prop | type | default | description |
| -------------- | ----------------- | ------- | ------------------------------------------------------ |
| `children` | `React.ReactNode` | - | 内容区，通常为标题与说明 |
| `className` | `string` | - | 内容区额外 class |
| `...ViewProps` | `ViewProps` | - | 支持全部标准 React Native `View` 属性 |
### ListGroup.ItemTitle
| prop | type | default | description |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | - | 标题文本或自定义内容 |
| `className` | `string` | - | 标题额外 class |
| `...ViewProps` | `ViewProps` | - | 支持全部标准 React Native `View` 属性 |
### ListGroup.ItemDescription
| prop | type | default | description |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | - | 说明文本或自定义内容 |
| `className` | `string` | - | 说明额外 class |
| `...ViewProps` | `ViewProps` | - | 支持全部标准 React Native `View` 属性 |
### ListGroup.ItemSuffix
| prop | type | default | description |
| -------------- | -------------------- | ------- | ---------------------------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 自定义尾部内容；提供时将覆盖默认右箭头图标 |
| `className` | `string` | - | 尾部额外 class |
| `iconProps` | `ListGroupIconProps` | - | 自定义默认右箭头图标；仅在无 `children` 时生效 |
| `...ViewProps` | `ViewProps` | - | 支持全部标准 React Native `View` 属性 |
#### ListGroupIconProps
| prop | type | default | description |
| ------- | -------- | ------------------- | ---------------------------------- |
| `size` | `number` | `16` | 箭头图标尺寸（像素） |
| `color` | `string` | 主题的 `muted` 颜色 | 箭头图标颜色 |
apps/docs/content/docs/cn/native/components/(navigation)/tabs.mdx
+579
View File
@@ -0,0 +1,579 @@
---
title: Tabs 标签页
description: 使用选项卡视图组织内容，支持动画过渡与指示器。
links:
source_native: tabs/tabs.tsx
styles_native: tabs/tabs.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/tabs-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/tabs-docs-dark.mp4"
/>
## 导入
```tsx
import { Tabs } from 'heroui-native';
```
## 结构
```tsx
<Tabs>
<Tabs.List>
<Tabs.ScrollView>
<Tabs.Indicator />
<Tabs.Trigger>
<Tabs.Label>...</Tabs.Label>
</Tabs.Trigger>
<Tabs.Separator />
<Tabs.Trigger>
<Tabs.Label>...</Tabs.Label>
</Tabs.Trigger>
</Tabs.ScrollView>
</Tabs.List>
<Tabs.Content>...</Tabs.Content>
</Tabs>
```
- **Tabs**：管理选项卡状态与选中的根容器。控制当前激活项、处理值变化，并向子组件提供上下文。
- **Tabs.List**：放置选项卡触发器的容器。将多个触发器组合在一起，并支持 `primary` 或 `secondary` 等样式变体。
- **Tabs.ScrollView**：可选的横向滚动容器。当标签溢出时可横向滚动，并可在选中时自动居中。
- **Tabs.Trigger**：每个选项卡的交互触发器。处理按压以切换激活项，并测量位置以驱动指示器动画。
- **Tabs.Label**：触发器上的文字标签，用于展示选项卡标题及对应样式。
- **Tabs.Indicator**：当前激活项的可视指示器，可在选项卡之间以弹簧或时长动画平滑过渡。
- **Tabs.Separator**：选项卡之间的分隔线。当当前值不在 `betweenValues` 数组中时显示，并带有透明度过渡动画。
- **Tabs.Content**：面板内容容器。当其 `value` 与当前激活项一致时显示对应内容。
## 用法
### 基础用法
Tabs 使用复合子组件，将内容划分为可切换的区域。
```tsx
<Tabs defaultValue="tab1">
<Tabs.List>
<Tabs.Indicator />
<Tabs.Trigger value="tab1">
<Tabs.Label>标签一</Tabs.Label>
</Tabs.Trigger>
<Tabs.Trigger value="tab2">
<Tabs.Label>标签二</Tabs.Label>
</Tabs.Trigger>
</Tabs.List>
<Tabs.Content value="tab1">...</Tabs.Content>
<Tabs.Content value="tab2">...</Tabs.Content>
</Tabs>
```
### 主样式（primary）
默认圆角主样式，选中项背后为填充指示器。
```tsx
<Tabs value={activeTab} onValueChange={setActiveTab} variant="primary">
<Tabs.List>
<Tabs.Indicator />
<Tabs.Trigger value="settings">
<Tabs.Label>设置</Tabs.Label>
</Tabs.Trigger>
<Tabs.Trigger value="profile">
<Tabs.Label>个人资料</Tabs.Label>
</Tabs.Trigger>
</Tabs.List>
<Tabs.Content value="settings">...</Tabs.Content>
<Tabs.Content value="profile">...</Tabs.Content>
</Tabs>
```
### 次样式（secondary）
下划线指示器，视觉更轻量。
```tsx
<Tabs value={activeTab} onValueChange={setActiveTab} variant="secondary">
<Tabs.List>
<Tabs.Indicator />
<Tabs.Trigger value="overview">
<Tabs.Label>概览</Tabs.Label>
</Tabs.Trigger>
<Tabs.Trigger value="analytics">
<Tabs.Label>分析</Tabs.Label>
</Tabs.Trigger>
</Tabs.List>
<Tabs.Content value="overview">...</Tabs.Content>
<Tabs.Content value="analytics">...</Tabs.Content>
</Tabs>
```
### 可滚动标签
标签较多时通过横向滚动容纳。
```tsx
<Tabs value={activeTab} onValueChange={setActiveTab}>
<Tabs.List>
<Tabs.ScrollView scrollAlign="center">
<Tabs.Indicator />
<Tabs.Trigger value="tab1">
<Tabs.Label>第一个</Tabs.Label>
</Tabs.Trigger>
<Tabs.Trigger value="tab2">
<Tabs.Label>第二个</Tabs.Label>
</Tabs.Trigger>
<Tabs.Trigger value="tab3">
<Tabs.Label>第三个</Tabs.Label>
</Tabs.Trigger>
<Tabs.Trigger value="tab4">
<Tabs.Label>第四个</Tabs.Label>
</Tabs.Trigger>
<Tabs.Trigger value="tab5">
<Tabs.Label>第五个</Tabs.Label>
</Tabs.Trigger>
</Tabs.ScrollView>
</Tabs.List>
<Tabs.Content value="tab1">...</Tabs.Content>
<Tabs.Content value="tab2">...</Tabs.Content>
<Tabs.Content value="tab3">...</Tabs.Content>
<Tabs.Content value="tab4">...</Tabs.Content>
<Tabs.Content value="tab5">...</Tabs.Content>
</Tabs>
```
### 禁用标签
使用 `isDisabled` 禁止与特定标签交互。
```tsx
<Tabs value={activeTab} onValueChange={setActiveTab}>
<Tabs.List>
<Tabs.Indicator />
<Tabs.Trigger value="active">
<Tabs.Label>可用</Tabs.Label>
</Tabs.Trigger>
<Tabs.Trigger value="disabled" isDisabled>
<Tabs.Label>已禁用</Tabs.Label>
</Tabs.Trigger>
<Tabs.Trigger value="another">
<Tabs.Label>其他</Tabs.Label>
</Tabs.Trigger>
</Tabs.List>
<Tabs.Content value="active">...</Tabs.Content>
<Tabs.Content value="another">...</Tabs.Content>
</Tabs>
```
### 与图标组合
图标与文字并用，信息更直观。
```tsx
<Tabs value={activeTab} onValueChange={setActiveTab}>
<Tabs.List>
<Tabs.Indicator />
<Tabs.Trigger value="home">
<Icon name="home" size={16} />
<Tabs.Label>首页</Tabs.Label>
</Tabs.Trigger>
<Tabs.Trigger value="search">
<Icon name="search" size={16} />
<Tabs.Label>搜索</Tabs.Label>
</Tabs.Trigger>
</Tabs.List>
<Tabs.Content value="home">...</Tabs.Content>
<Tabs.Content value="search">...</Tabs.Content>
</Tabs>
```
### 使用渲染函数
在 `Tabs.Trigger` 上使用渲染函数，可读取选中状态并按需自定义内容。
```tsx
<Tabs value={activeTab} onValueChange={setActiveTab}>
<Tabs.List>
<Tabs.Indicator />
<Tabs.Trigger value="settings">
{({ isSelected, value, isDisabled }) => (
<Tabs.Label
className={isSelected ? 'text-accent font-medium' : 'text-foreground'}
>
设置
</Tabs.Label>
)}
</Tabs.Trigger>
<Tabs.Trigger value="profile">
{({ isSelected }) => (
<>
<Icon name="user" size={16} />
<Tabs.Label className={isSelected ? 'text-accent' : 'text-muted'}>
个人资料
</Tabs.Label>
</>
)}
</Tabs.Trigger>
</Tabs.List>
<Tabs.Content value="settings">...</Tabs.Content>
<Tabs.Content value="profile">...</Tabs.Content>
</Tabs>
```
### 与分隔线配合
在标签之间添加分隔线；可见性由 `betweenValues` 与当前激活项共同决定（详见下方 API）。
```tsx
<Tabs value={activeTab} onValueChange={setActiveTab}>
<Tabs.List>
<Tabs.ScrollView>
<Tabs.Indicator />
<Tabs.Trigger value="general">
<Tabs.Label>通用</Tabs.Label>
</Tabs.Trigger>
<Tabs.Separator betweenValues={['general', 'notifications']} />
<Tabs.Trigger value="notifications">
<Tabs.Label>通知</Tabs.Label>
</Tabs.Trigger>
<Tabs.Separator betweenValues={['notifications', 'profile']} />
<Tabs.Trigger value="profile">
<Tabs.Label>个人资料</Tabs.Label>
</Tabs.Trigger>
</Tabs.ScrollView>
</Tabs.List>
<Tabs.Content value="general">...</Tabs.Content>
<Tabs.Content value="notifications">...</Tabs.Content>
<Tabs.Content value="profile">...</Tabs.Content>
</Tabs>
```
## 示例
```tsx
import {
Button,
Checkbox,
Description,
ControlField,
Label,
Tabs,
TextField,
} from 'heroui-native';
import { useState } from 'react';
import { View, Text } from 'react-native';
import Animated, {
FadeIn,
FadeOut,
LinearTransition,
} from 'react-native-reanimated';
const AnimatedContentContainer = ({
children,
}: {
children: React.ReactNode;
}) => (
<Animated.View
entering={FadeIn.duration(200)}
exiting={FadeOut.duration(200)}
className="gap-6"
>
{children}
</Animated.View>
);
export default function TabsExample() {
const [activeTab, setActiveTab] = useState('general');
const [showSidebar, setShowSidebar] = useState(true);
const [accountActivity, setAccountActivity] = useState(true);
const [name, setName] = useState('');
return (
<Tabs value={activeTab} onValueChange={setActiveTab} variant="primary">
<Tabs.List>
<Tabs.ScrollView>
<Tabs.Indicator />
<Tabs.Trigger value="general">
<Tabs.Label>通用</Tabs.Label>
</Tabs.Trigger>
<Tabs.Trigger value="notifications">
<Tabs.Label>通知</Tabs.Label>
</Tabs.Trigger>
<Tabs.Trigger value="profile">
<Tabs.Label>个人资料</Tabs.Label>
</Tabs.Trigger>
</Tabs.ScrollView>
</Tabs.List>
<Animated.View
layout={LinearTransition.duration(200)}
className="px-4 py-6 border border-border rounded-xl"
>
<Tabs.Content value="general">
<AnimatedContentContainer>
<ControlField
isSelected={showSidebar}
onSelectedChange={setShowSidebar}
>
<ControlField.Indicator variant="checkbox" />
<View className="flex-1">
<Label>显示侧边栏</Label>
<Description>显示侧边导航面板</Description>
</View>
</ControlField>
</AnimatedContentContainer>
</Tabs.Content>
<Tabs.Content value="notifications">
<AnimatedContentContainer>
<ControlField
isSelected={accountActivity}
onSelectedChange={setAccountActivity}
>
<ControlField.Indicator variant="checkbox" />
<View className="flex-1">
<Label>账户动态</Label>
<Description>接收与账户活动相关的通知</Description>
</View>
</ControlField>
</AnimatedContentContainer>
</Tabs.Content>
<Tabs.Content value="profile">
<AnimatedContentContainer>
<TextField isRequired>
<Label>姓名</Label>
<Input
value={name}
onChangeText={setName}
placeholder="请输入全名"
/>
</TextField>
<Button size="sm" className="self-start">
<Button.Label>更新资料</Button.Label>
</Button>
</AnimatedContentContainer>
</Tabs.Content>
</Animated.View>
</Tabs>
);
}
```
更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/tabs.tsx>)。
## API 参考
### Tabs
| prop | type | 默认值 | 描述 |
| --------------- | ---------------------------- | ---------- | ---------------------------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 渲染在 Tabs 内的子元素 |
| `value` | `string` | - | 当前激活的标签值 |
| `variant` | `'primary' \| 'secondary'` | `'primary'` | 视觉变体 |
| `className` | `string` | - | 根容器额外 className |
| `animation` | `"disable-all" \| undefined` | `undefined` | 动画配置。设为 `"disable-all"` 可关闭全部动画（含子树） |
| `onValueChange` | `(value: string) => void` | - | 激活标签变化时的回调 |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部标准属性 |
### Tabs.List
| prop | type | 默认值 | 描述 |
| -------------- | ----------------- | ------ | ------------------------------------------- |
| `children` | `React.ReactNode` | - | 渲染在列表内的子元素 |
| `className` | `string` | - | 额外 className |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部标准属性 |
### Tabs.ScrollView
| prop | type | 默认值 | 描述 |
| --------------------------- | ---------------------------------------- | --------- | ------------------------------------------------- |
| `children` | `React.ReactNode` | - | 渲染在滚动视图内的子元素 |
| `scrollAlign` | `'start' \| 'center' \| 'end' \| 'none'` | `'center'` | 选中项的滚动对齐方式 |
| `className` | `string` | - | 滚动容器额外 className |
| `contentContainerClassName` | `string` | - | 内容容器额外 className |
| `...ScrollViewProps` | `ScrollViewProps` | - | 支持 React Native `ScrollView` 的全部标准属性 |
### Tabs.Trigger
| prop | type | 默认值 | 描述 |
| ------------------- | ------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------ |
| `children` | `React.ReactNode \| ((props: TabsTriggerRenderProps) => React.ReactNode)` | - | 子节点，或接收 `TabsTriggerRenderProps` 的渲染函数 |
| `value` | `string` | - | 唯一标识该标签的值 |
| `isDisabled` | `boolean` | `false` | 是否禁用该触发器 |
| `className` | `string` | - | 额外 className |
| `...PressableProps` | `PressableProps` | - | 支持 React Native `Pressable` 的全部标准属性 |
#### TabsTriggerRenderProps
使用渲染函数作为 `children` 时，会传入以下属性：
| property | type | 描述 |
| ------------ | --------- | ------------------------ |
| `isSelected` | `boolean` | 当前触发器是否被选中 |
| `value` | `string` | 该触发器的值 |
| `isDisabled` | `boolean` | 该触发器是否禁用 |
### Tabs.Label
| prop | type | 默认值 | 描述 |
| -------------- | ----------------- | ------ | ------------------------------------------- |
| `children` | `React.ReactNode` | - | 作为标签渲染的文本内容 |
| `className` | `string` | - | 额外 className |
| `...TextProps` | `TextProps` | - | 支持 React Native `Text` 的全部标准属性 |
### Tabs.Indicator
| prop | type | 默认值 | 描述 |
| ----------------------- | ------------------------ | ------ | ----------------------------------------------------- |
| `children` | `React.ReactNode` | - | 自定义指示器内容 |
| `className` | `string` | - | 额外 className |
| `animation` | `TabsIndicatorAnimation` | - | 动画配置 |
| `isAnimatedStyleActive` | `boolean` | `true` | 是否启用 Reanimated 动画样式 |
| `...Animated.ViewProps` | `Animated.ViewProps` | - | 支持 Reanimated `Animated.View` 的全部属性 |
#### TabsIndicatorAnimation
`Tabs.Indicator` 的动画配置，可为：
- `false` 或 `"disabled"`：关闭所有动画
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | 默认值 | 描述 |
| ------------------- | -------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------- |
| `state` | `'disabled' \| boolean` | - | 自定义属性时用于禁用动画 |
| `width.type` | `'spring' \| 'timing'` | `'spring'` | 宽度动画类型 |
| `width.config` | `WithSpringConfig \| WithTimingConfig` | `{ stiffness: 1200, damping: 120 }`（spring）或 `{ duration: 200 }`（timing） | Reanimated 动画配置 |
| `height.type` | `'spring' \| 'timing'` | `'spring'` | 高度动画类型 |
| `height.config` | `WithSpringConfig \| WithTimingConfig` | 同上 | Reanimated 动画配置 |
| `translateX.type` | `'spring' \| 'timing'` | `'spring'` | 水平位移动画类型 |
| `translateX.config` | `WithSpringConfig \| WithTimingConfig` | 同上 | Reanimated 动画配置 |
### Tabs.Separator
| prop | type | 默认值 | 描述 |
| ----------------------- | ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `betweenValues` | `string[]` | - | 分隔线两侧对应的标签值数组。当**当前**标签值**不在**该数组中时，分隔线可见（与可见性动画联动） |
| `isAlwaysVisible` | `boolean` | `false` | 为 `true` 时透明度恒为 1，不受当前标签影响 |
| `className` | `string` | - | 额外 className |
| `animation` | `TabsSeparatorAnimation` | - | 动画配置 |
| `isAnimatedStyleActive` | `boolean` | `true` | 是否启用 Reanimated 动画样式 |
| `children` | `React.ReactNode` | - | 自定义分隔线内容 |
| `...Animated.ViewProps` | `Animated.ViewProps` | - | 支持 Reanimated `Animated.View` 的全部属性 |
**说明：** 以下样式属性由动画占用，不能仅通过 `className` 覆盖：
- `opacity`：用于分隔线显隐过渡（当前标签在 `betweenValues` 内时为 0，否则为 1）
若要调整这些属性，请使用 `animation`。若需完全关闭动画样式、改用自己的 `className` 或 `style`，请设置 `isAnimatedStyleActive={false}`。
#### TabsSeparatorAnimation
`Tabs.Separator` 的动画配置，可为：
- `false` 或 `"disabled"`：关闭所有动画
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | 默认值 | 描述 |
| ---------------------- | ----------------------- | ------------------ | ---------------------------------- |
| `state` | `'disabled' \| boolean` | - | 自定义属性时用于禁用动画 |
| `opacity.value` | `[number, number]` | `[0, 1]` | 透明度区间 [隐藏, 显示] |
| `opacity.timingConfig` | `WithTimingConfig` | `{ duration: 200 }` | 时长类动画配置 |
### Tabs.Content
| prop | type | 默认值 | 描述 |
| -------------- | ----------------- | ------ | ------------------------------------------- |
| `children` | `React.ReactNode` | - | 渲染在面板内的子元素 |
| `value` | `string` | - | 该内容与哪个标签值对应 |
| `className` | `string` | - | 额外 className |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部标准属性 |
## Hooks
### useTabs
在自定义组件或复合子组件中读取 Tabs 根上下文。
```tsx
import { useTabs } from 'heroui-native';
const CustomComponent = () => {
const { value, onValueChange, nativeID } = useTabs();
// ...你的实现
};
```
#### 返回值
类型：`UseTabsReturn`
| property | type | 描述 |
| --------------- | ------------------------- | ------------------------ |
| `value` | `string` | 当前激活的标签值 |
| `onValueChange` | `(value: string) => void` | 用于切换激活标签的回调 |
| `nativeID` | `string` | 该 Tabs 实例的唯一标识 |
**说明：** 必须在 `Tabs` 内使用；在上下文外调用会抛错。
### useTabsMeasurements
读取标签测量上下文，用于管理各触发器的位置与尺寸。
```tsx
import { useTabsMeasurements } from 'heroui-native';
const CustomIndicator = () => {
const { measurements, variant } = useTabsMeasurements();
// ...你的实现
};
```
#### 返回值
类型：`UseTabsMeasurementsReturn`
| property | type | 描述 |
| ----------------- | ------------------------------------------------------- | ---------------------------------- |
| `measurements` | `Record<string, ItemMeasurements>` | 各标签触发器的测量数据 |
| `setMeasurements` | `(key: string, measurements: ItemMeasurements) => void` | 更新指定触发器的测量数据 |
| `variant` | `'primary' \| 'secondary'` | 当前 Tabs 的视觉变体 |
#### ItemMeasurements
| property | type | 描述 |
| -------- | -------- | -------------------- |
| `width` | `number` | 触发器宽度（像素） |
| `height` | `number` | 触发器高度（像素） |
| `x` | `number` | 触发器的 x 坐标 |
**说明：** 必须在 `Tabs` 内使用；在上下文外调用会抛错。
### useTabsTrigger
在自定义组件或复合子组件中读取单个 `Tabs.Trigger` 的上下文。
```tsx
import { useTabsTrigger } from 'heroui-native';
const CustomLabel = () => {
const { value, isSelected, nativeID } = useTabsTrigger();
// ...你的实现
};
```
#### 返回值
类型：`UseTabsTriggerReturn`
| property | type | 描述 |
| ------------ | --------- | ------------------------ |
| `value` | `string` | 该触发器的值 |
| `nativeID` | `string` | 该触发器的唯一标识 |
| `isSelected` | `boolean` | 当前触发器是否被选中 |
**说明：** 必须在 `Tabs.Trigger` 内使用；在上下文外调用会抛错。
apps/docs/content/docs/cn/native/components/(overlays)/bottom-sheet.mdx
+359
View File
@@ -0,0 +1,359 @@
---
title: BottomSheet 底部弹层
description: 自底部滑入的底部表单，带动画与下滑关闭手势。
icon: updated
links:
source_native: bottom-sheet/bottom-sheet.tsx
styles_native: bottom-sheet/bottom-sheet.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/bottom-sheet-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/bottom-sheet-docs-dark.mp4"
/>
## 导入
```tsx
import { BottomSheet } from 'heroui-native';
```
## 结构
```tsx
<BottomSheet>
<BottomSheet.Trigger>...</BottomSheet.Trigger>
<BottomSheet.Portal>
<BottomSheet.Overlay>...</BottomSheet.Overlay>
<BottomSheet.Content>
<BottomSheet.Close />
<BottomSheet.Title>...</BottomSheet.Title>
<BottomSheet.Description>...</BottomSheet.Description>
</BottomSheet.Content>
</BottomSheet.Portal>
</BottomSheet>
```
- **BottomSheet**：根组件，管理开关状态并向子级提供上下文。
- **BottomSheet.Trigger**：按下后打开底部表单的可按压区域。
- **BottomSheet.Portal**：在 Portal 中渲染，使用全屏覆盖层。
- **BottomSheet.Overlay**：覆盖全屏的背景层，按下通常可关闭。
- **BottomSheet.Content**：主容器，基于 @gorhom/bottom-sheet 渲染并支持手势。
- **BottomSheet.Close**：关闭按钮；可自定义子节点或使用默认关闭图标。
- **BottomSheet.Title**：标题，语义标题角色并关联无障碍。
- **BottomSheet.Description**：说明文字，并关联无障碍。
## 用法
### 基础底部表单
包含标题、描述与关闭按钮的简单示例。
```tsx
<BottomSheet>
<BottomSheet.Trigger asChild>
<Button>打开底部表单</Button>
</BottomSheet.Trigger>
<BottomSheet.Portal>
<BottomSheet.Overlay />
<BottomSheet.Content>
<BottomSheet.Close />
<BottomSheet.Title>...</BottomSheet.Title>
<BottomSheet.Description>...</BottomSheet.Description>
</BottomSheet.Content>
</BottomSheet.Portal>
</BottomSheet>
```
### 悬浮（Detached）
与底边留出间距的悬浮样式。
```tsx
<BottomSheet>
<BottomSheet.Trigger>...</BottomSheet.Trigger>
<BottomSheet.Portal>
<BottomSheet.Overlay />
<BottomSheet.Content
detached={true}
bottomInset={insets.bottom + 12}
className="mx-4"
backgroundClassName="rounded-[32px]"
>
...
</BottomSheet.Content>
</BottomSheet.Portal>
</BottomSheet>
```
### 多停靠点与滚动
多档高度与可滚动内容。
```tsx
<BottomSheet>
<BottomSheet.Trigger>...</BottomSheet.Trigger>
<BottomSheet.Portal>
<BottomSheet.Overlay />
<BottomSheet.Content snapPoints={['25%', '50%', '90%']}>
<ScrollView>...</ScrollView>
</BottomSheet.Content>
</BottomSheet.Portal>
</BottomSheet>
```
### 自定义遮罩
用模糊等自定义内容替换默认遮罩。
```tsx
import { useBottomSheet, useBottomSheetAnimation } from 'heroui-native';
import { StyleSheet, Pressable } from 'react-native';
import { interpolate, useDerivedValue } from 'react-native-reanimated';
import { AnimatedBlurView } from './animated-blur-view';
import { useUniwind } from 'uniwind';
export const BottomSheetBlurOverlay = () => {
const { theme } = useUniwind();
const { onOpenChange } = useBottomSheet();
const { progress } = useBottomSheetAnimation();
const blurIntensity = useDerivedValue(() => {
return interpolate(progress.get(), [0, 1, 2], [0, 40, 0]);
});
return (
<Pressable
style={StyleSheet.absoluteFill}
onPress={() => onOpenChange(false)}
>
<AnimatedBlurView
blurIntensity={blurIntensity}
tint={theme === 'dark' ? 'dark' : 'systemUltraThinMaterialDark'}
style={StyleSheet.absoluteFill}
/>
</Pressable>
);
};
```
```tsx
<BottomSheet>
<BottomSheet.Trigger>...</BottomSheet.Trigger>
<BottomSheet.Portal>
<BottomSheetBlurOverlay />
<BottomSheet.Content>...</BottomSheet.Content>
</BottomSheet.Portal>
</BottomSheet>
```
## 示例
```tsx
import { BottomSheet, Button } from 'heroui-native';
import { useState } from 'react';
import { View } from 'react-native';
import { withUniwind } from 'uniwind';
import Ionicons from '@expo/vector-icons/Ionicons';
const StyledIonicons = withUniwind(Ionicons);
export default function BottomSheetExample() {
const [isOpen, setIsOpen] = useState(false);
return (
<BottomSheet isOpen={isOpen} onOpenChange={setIsOpen}>
<BottomSheet.Trigger asChild>
<Button variant="secondary">打开底部表单</Button>
</BottomSheet.Trigger>
<BottomSheet.Portal>
<BottomSheet.Overlay />
<BottomSheet.Content>
<View className="items-center mb-5">
<View className="size-20 items-center justify-center rounded-full bg-green-500/10">
<StyledIonicons
name="shield-checkmark"
size={40}
className="text-green-500"
/>
</View>
</View>
<View className="mb-8 gap-2 items-center">
<BottomSheet.Title className="text-center">
保持安全
</BottomSheet.Title>
<BottomSheet.Description className="text-center">
将软件更新到最新版本，以获得更好的安全性与性能。
</BottomSheet.Description>
</View>
<View className="gap-3">
<Button onPress={() => setIsOpen(false)}>立即更新</Button>
<Button variant="tertiary" onPress={() => setIsOpen(false)}>
稍后
</Button>
</View>
</BottomSheet.Content>
</BottomSheet.Portal>
</BottomSheet>
);
}
```
更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/bottom-sheet.tsx)。
## API 参考
### BottomSheet
| prop | type | default | description |
| --------------- | -------------------------- | ------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | - | 触发器与底部表单内容 |
| `isOpen` | `boolean` | - | 受控开关状态 |
| `isDefaultOpen` | `boolean` | `false` | 非受控初始是否打开 |
| `animation` | `AnimationRootDisableAll` | - | 动画配置 |
| `onOpenChange` | `(value: boolean) => void` | - | 开关状态变化回调 |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部属性 |
#### 动画配置
根动画配置，可为：
- `"disable-all"`：禁用全部动画（含子级）
- `undefined`：使用默认动画
### BottomSheet.Trigger
| prop | type | default | description |
| -------------------------- | ----------------------- | ------- | -------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 触发器内容 |
| `asChild` | `boolean` | - | 是否无包裹渲染为子元素 |
| `...TouchableOpacityProps` | `TouchableOpacityProps` | - | 支持 React Native `TouchableOpacity` 的全部属性 |
### BottomSheet.Portal
| prop | type | default | description |
| -------------------------------------------- | ---------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | Portal 内容（遮罩与底部表单） |
| `disableFullWindowOverlay` | `boolean` | `false` | iOS 为 true 时使用普通 `View` 替代 `FullWindowOverlay`，便于检查器；遮罩不再叠在原生模态之上 |
| `unstable_accessibilityContainerViewIsModal` | `boolean` | `false` | 是否将覆盖窗口视为模态容器（VoiceOver）。仅 iOS；可能随 react-native-screens 变化 |
| `className` | `string` | - | Portal 容器额外 class |
| `style` | `StyleProp<ViewStyle>` | - | Portal 容器额外样式 |
| `hostName` | `string` | - | 可选 Portal 宿主名 |
| `forceMount` | `boolean` | - | 关闭时仍挂载以配合动画 |
### BottomSheet.Overlay
| prop | type | default | description |
| ----------------------- | ------------------------------------------------------ | ------- | ------------------------------------------------------------ |
| `children` | `React.ReactNode` | - | 自定义遮罩内容 |
| `className` | `string` | - | 遮罩额外 class |
| `style` | `ViewStyle` | - | 遮罩容器样式 |
| `animation` | `Omit<PopupOverlayAnimation, 'entering' \| 'exiting'>` | - | 动画配置 |
| `isAnimatedStyleActive` | `boolean` | `true` | 是否启用 Reanimated 动画样式 |
| `isCloseOnPress` | `boolean` | `true` | 按下遮罩是否关闭 |
| `...PressableProps` | `PressableProps` | - | 支持 React Native `Pressable` 的全部属性 |
#### 动画配置
遮罩动画配置，可为：
- `false` 或 `"disabled"`：禁用全部动画
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置（不含 `entering` / `exiting`）
| prop | type | default | description |
| --------------- | -------------------------- | ----------- | ----------------------------------------------- |
| `state` | `'disabled' \| boolean` | - | 在自定义属性时禁用动画 |
| `opacity.value` | `[number, number, number]` | `[0, 1, 0]` | 不透明度 [空闲, 打开, 关闭] |
### BottomSheet.Content
| prop | type | default | description |
| --------------------------- | ---------------------------------------- | ------- | -------------------------------------------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 底部表单内容 |
| `className` | `string` | - | 容器额外 class |
| `containerClassName` | `string` | - | 外层容器 class |
| `contentContainerClassName` | `string` | - | 内容区 class |
| `backgroundClassName` | `string` | - | 背景 class |
| `handleClassName` | `string` | - | 拖动手柄区域 class |
| `handleIndicatorClassName` | `string` | - | 手柄指示条 class |
| `contentContainerProps` | `Omit<BottomSheetViewProps, 'children'>` | - | 内容容器 props |
| `animation` | `AnimationDisabled` | - | 动画配置 |
| `...GorhomBottomSheetProps` | `Partial<GorhomBottomSheetProps>` | - | 支持 [@gorhom/bottom-sheet 全部 props](https://gorhom.dev/react-native-bottom-sheet/props) |
**说明：** 内容区内可使用 [@gorhom/bottom-sheet 组件](https://gorhom.dev/react-native-bottom-sheet/components/bottomsheetview)，如 `BottomSheetView`、`BottomSheetScrollView`、`BottomSheetFlatList` 等。
### BottomSheet.Close
`BottomSheet.Close` 继承 [CloseButton](./close-button)，按下时自动关闭底部表单。
### BottomSheet.Title
| prop | type | default | description |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | - | 标题内容 |
| `className` | `string` | - | 标题额外 class |
| `...TextProps` | `TextProps` | - | 支持 React Native `Text` 的全部属性 |
### BottomSheet.Description
| prop | type | default | description |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | - | 描述内容 |
| `className` | `string` | - | 描述额外 class |
| `...TextProps` | `TextProps` | - | 支持 React Native `Text` 的全部属性 |
## Hooks
### useBottomSheet
访问底部表单原语上下文。
```tsx
const { isOpen, onOpenChange } = useBottomSheet();
```
| property | type | description |
| -------------- | -------------------------- | ----------------- |
| `isOpen` | `boolean` | 当前是否打开 |
| `onOpenChange` | `(value: boolean) => void` | 修改开关状态 |
### useBottomSheetAnimation
访问底部表单动画上下文。
```tsx
const { progress } = useBottomSheetAnimation();
```
| property | type | description |
| ---------- | --------------------- | -------------------------------------------- |
| `progress` | `SharedValue<number>` | 动画进度（0=空闲，1=打开，2=关闭） |
## 特别说明
### 元素检查器（iOS）
`BottomSheet` 在 iOS 使用 `FullWindowOverlay`，位于独立原生窗口，会破坏 React Native 元素检查器。开发时可在 `BottomSheet.Portal` 设置 `disableFullWindowOverlay={true}`。代价：底部表单将无法叠在原生系统模态之上。
### 关闭回调
建议使用 `BottomSheet` 的 `onOpenChange` 处理关闭逻辑，可在所有关闭场景可靠触发（下滑、点遮罩、点关闭、程序化关闭等）。
```tsx
<BottomSheet
isOpen={isOpen}
onOpenChange={(value) => {
setIsOpen(value);
if (!value) {
// 任意方式关闭时都会执行
yourCallbackOnClose();
}
}}
>
...
</BottomSheet>
```
**说明：** `@gorhom/bottom-sheet` 在 `BottomSheet.Content` 上的 `onClose` 仅在下滑关闭时触发，点遮罩、关闭按钮或程序化关闭不会触发。需要可靠关闭回调时请使用根组件的 `onOpenChange`。
apps/docs/content/docs/cn/native/components/(overlays)/dialog.mdx
+299
View File
@@ -0,0 +1,299 @@
---
title: Dialog 对话框
description: 模态浮层，带动画过渡并支持手势关闭。
icon: updated
links:
source_native: dialog/dialog.tsx
styles_native: dialog/dialog.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/dialog-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/dialog-docs-dark.mp4"
/>
## 导入
```tsx
import { Dialog } from 'heroui-native';
```
## 结构
```tsx
<Dialog>
<Dialog.Trigger>...</Dialog.Trigger>
<Dialog.Portal>
<Dialog.Overlay>...</Dialog.Overlay>
<Dialog.Content>
<Dialog.Close>...</Dialog.Close>
<Dialog.Title>...</Dialog.Title>
<Dialog.Description>...</Dialog.Description>
</Dialog.Content>
</Dialog.Portal>
</Dialog>
```
- **Dialog**：根组件，管理开关状态并向子级提供上下文。
- **Dialog.Trigger**：按下后打开对话框的可按压区域。
- **Dialog.Portal**：在 Portal 中渲染内容，居中布局并控制动画。
- **Dialog.Overlay**：内容背后的遮罩，按下通常可关闭对话框。
- **Dialog.Content**：主容器，支持拖拽关闭等手势。
- **Dialog.Close**：关闭按钮；可自定义子节点或使用默认关闭图标。
- **Dialog.Title**：标题，语义为标题角色。
- **Dialog.Description**：补充说明文字。
## 用法
### 基础对话框
包含标题、描述与关闭按钮的简单对话框。
```tsx
<Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
<Dialog.Trigger asChild>
<Button>打开对话框</Button>
</Dialog.Trigger>
<Dialog.Portal>
<Dialog.Overlay />
<Dialog.Content>
<Dialog.Close />
<Dialog.Title>...</Dialog.Title>
<Dialog.Description>...</Dialog.Description>
</Dialog.Content>
</Dialog.Portal>
</Dialog>
```
### 可滚动内容
长内容使用滚动容器承载。
```tsx
<Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
<Dialog.Trigger>...</Dialog.Trigger>
<Dialog.Portal>
<Dialog.Overlay />
<Dialog.Content>
<Dialog.Close />
<Dialog.Title>...</Dialog.Title>
<View className="h-[300px]">
<ScrollView>...</ScrollView>
</View>
</Dialog.Content>
</Dialog.Portal>
</Dialog>
```
### 表单对话框
包含输入与键盘避让的对话框。
```tsx
<Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
<Dialog.Trigger>...</Dialog.Trigger>
<Dialog.Portal>
<Dialog.Overlay />
<KeyboardAvoidingView behavior="padding">
<Dialog.Content>
<Dialog.Close />
<Dialog.Title>...</Dialog.Title>
<TextField>...</TextField>
<Button onPress={handleSubmit}>提交</Button>
</Dialog.Content>
</KeyboardAvoidingView>
</Dialog.Portal>
</Dialog>
```
## 示例
```tsx
import { Button, Dialog } from 'heroui-native';
import { View } from 'react-native';
import { useState } from 'react';
export default function DialogExample() {
const [isOpen, setIsOpen] = useState(false);
return (
<Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
<Dialog.Trigger asChild>
<Button variant="primary">打开对话框</Button>
</Dialog.Trigger>
<Dialog.Portal>
<Dialog.Overlay />
<Dialog.Content>
<Dialog.Close variant="ghost" />
<View className="mb-5 gap-1.5">
<Dialog.Title>确认操作</Dialog.Title>
<Dialog.Description>
确定要继续吗？此操作无法撤销。
</Dialog.Description>
</View>
<View className="flex-row justify-end gap-3">
<Button variant="ghost" size="sm" onPress={() => setIsOpen(false)}>
取消
</Button>
<Button size="sm">确认</Button>
</View>
</Dialog.Content>
</Dialog.Portal>
</Dialog>
);
}
```
更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/dialog.tsx)。
## API 参考
### Dialog
| prop | type | default | description |
| --------------- | -------------------------- | ------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | - | 触发器与对话框内容 |
| `isOpen` | `boolean` | - | 受控开关状态 |
| `isDefaultOpen` | `boolean` | `false` | 非受控初始是否打开 |
| `animation` | `AnimationRootDisableAll` | - | 动画配置 |
| `onOpenChange` | `(value: boolean) => void` | - | 开关状态变化回调 |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部属性 |
#### AnimationRootDisableAll
根动画配置，可为：
- `false` 或 `"disabled"`：仅禁用根级动画
- `"disable-all"`：禁用全部动画（含子级）
- `true` 或 `undefined`：使用默认动画
### Dialog.Trigger
| prop | type | default | description |
| -------------------------- | ----------------------- | ------- | -------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 触发器内容 |
| `asChild` | `boolean` | - | 是否无包裹渲染为子元素 |
| `...TouchableOpacityProps` | `TouchableOpacityProps` | - | 支持 React Native `TouchableOpacity` 的全部属性 |
### Dialog.Portal
| prop | type | default | description |
| -------------------------- | ---------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | Portal 内容（遮罩与对话框） |
| `disableFullWindowOverlay` | `boolean` | `false` | iOS 为 true 时使用普通 `View` 替代 `FullWindowOverlay`，便于检查器；遮罩不再叠在原生模态之上 |
| `unstable_accessibilityContainerViewIsModal` | `boolean` | `false` | 是否将覆盖窗口视为模态容器（VoiceOver）。仅 iOS；可能随 react-native-screens 变化 |
| `className` | `string` | - | Portal 容器额外 class |
| `style` | `StyleProp<ViewStyle>` | - | Portal 容器额外样式 |
| `hostName` | `string` | - | 可选 Portal 宿主名 |
| `forceMount` | `boolean` | - | 关闭时仍挂载以配合动画 |
### Dialog.Overlay
| prop | type | default | description |
| ----------------------- | ------------------------ | ------- | ------------------------------------------------------------ |
| `children` | `React.ReactNode` | - | 自定义遮罩内容 |
| `className` | `string` | - | 遮罩额外 class |
| `style` | `ViewStyle` | - | 遮罩容器样式 |
| `animation` | `DialogOverlayAnimation` | - | 动画配置 |
| `isAnimatedStyleActive` | `boolean` | `true` | 是否启用 Reanimated 动画样式 |
| `isCloseOnPress` | `boolean` | `true` | 按下遮罩是否关闭 |
| `forceMount` | `boolean` | - | 关闭时仍挂载以配合动画 |
| `...PressableProps` | `PressableProps` | - | 支持 React Native `Pressable` 的全部属性 |
#### DialogOverlayAnimation
遮罩动画配置，可为：
- `false` 或 `"disabled"`：禁用全部动画
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| --------------- | -------------------------- | ----------------------- | ---------------------------------------------------------------------------- |
| `state` | `'disabled' \| boolean` | - | 在自定义属性时禁用动画 |
| `opacity.value` | `[number, number, number]` | `[0, 1, 0]` | 不透明度 [空闲, 打开, 关闭]（基于进度，用于呈现） |
| `entering` | `EntryOrExitLayoutType` | `FadeIn.duration(200)` | 自定义进入动画（Popover 呈现用） |
| `exiting` | `EntryOrExitLayoutType` | `FadeOut.duration(150)` | 自定义退出动画（Popover 呈现用） |
### Dialog.Content
| prop | type | default | description |
| ----------------------- | ------------------------ | ------- | --------------------------------------------------- |
| `children` | `React.ReactNode` | - | 对话框内容 |
| `className` | `string` | - | 内容容器额外 class |
| `style` | `StyleProp<ViewStyle>` | - | 内容容器额外样式 |
| `animation` | `DialogContentAnimation` | - | 动画配置 |
| `isSwipeable` | `boolean` | `true` | 是否可滑动关闭 |
| `forceMount` | `boolean` | - | 关闭时仍挂载以配合动画 |
| `...Animated.ViewProps` | `Animated.ViewProps` | - | 支持 Reanimated `Animated.View` 的全部属性 |
#### DialogContentAnimation
内容动画配置，可为：
- `false` 或 `"disabled"`：禁用全部动画
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| ---------- | ----------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| `state` | `'disabled' \| boolean` | - | 在自定义属性时禁用动画 |
| `entering` | `EntryOrExitLayoutType` | 关键帧 `scale: 0.96→1` 与 `opacity: 0→1`（200ms，缓动 `Easing.out(Easing.ease)`） | 自定义进入动画 |
| `exiting` | `EntryOrExitLayoutType` | 关键帧 `scale: 1→0.96` 与 `opacity: 1→0`（150ms，缓动 `Easing.in(Easing.ease)`） | 自定义退出动画 |
### Dialog.Close
`Dialog.Close` 继承 [CloseButton](./close-button)，按下时自动关闭对话框。
### Dialog.Title
| prop | type | default | description |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | - | 标题内容 |
| `className` | `string` | - | 标题额外 class |
| `...TextProps` | `TextProps` | - | 支持 React Native `Text` 的全部属性 |
### Dialog.Description
| prop | type | default | description |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | - | 描述内容 |
| `className` | `string` | - | 描述额外 class |
| `...TextProps` | `TextProps` | - | 支持 React Native `Text` 的全部属性 |
## Hooks
### useDialog
访问对话框原语上下文。
```tsx
const { isOpen, onOpenChange } = useDialog();
```
| property | type | description |
| -------------- | -------------------------- | ----------------- |
| `isOpen` | `boolean` | 当前是否打开 |
| `onOpenChange` | `(value: boolean) => void` | 修改开关状态 |
### useDialogAnimation
访问对话框动画上下文，用于高级定制。
```tsx
const { progress, isDragging, isGestureReleaseAnimationRunning } =
useDialogAnimation();
```
| property | type | description |
| ---------------------------------- | ---------------------- | -------------------------------------------- |
| `progress` | `SharedValue<number>` | 动画进度（0=空闲，1=打开，2=关闭） |
| `isDragging` | `SharedValue<boolean>` | 是否正在拖拽 |
| `isGestureReleaseAnimationRunning` | `SharedValue<boolean>` | 手势释放动画是否进行中 |
## 特别说明
### 元素检查器（iOS）
`Dialog` 在 iOS 使用 `FullWindowOverlay`。开发时若需启用 React Native 元素检查器，可在 `Dialog.Portal` 设置 `disableFullWindowOverlay={true}`。代价：对话框将无法叠在原生系统模态之上。
apps/docs/content/docs/cn/native/components/(overlays)/popover.mdx
+531
View File
@@ -0,0 +1,531 @@
---
title: Popover 弹出框
description: 锚定在触发器上的浮动内容面板，支持方位与对齐选项。
icon: updated
links:
source_native: popover/popover.tsx
styles_native: popover/popover.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/popover-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/popover-docs-dark.mp4"
/>
## 导入
```tsx
import { Popover } from 'heroui-native';
```
## 结构
```tsx
<Popover>
<Popover.Trigger>...</Popover.Trigger>
<Popover.Portal>
<Popover.Overlay />
<Popover.Content>
<Popover.Arrow />
<Popover.Close />
<Popover.Title>...</Popover.Title>
<Popover.Description>...</Popover.Description>
</Popover.Content>
</Popover.Portal>
</Popover>
```
- **Popover**：根容器，管理展开/收起、定位，并为子组件提供上下文。
- **Popover.Trigger**：可点击的触发器，切换浮层可见性；为子元素包裹按压处理。
- **Popover.Portal**：在Portal层渲染内容，保证层级与定位正确。
- **Popover.Overlay**：可选背景遮罩；可透明或半透明，用于捕获外部点击。
- **Popover.Content**：内容容器，含定位、样式与碰撞检测；支持 `popover` 与底部抽屉呈现。
- **Popover.Arrow**：可选箭头，指向触发器；随 `placement` 自动定位。
- **Popover.Close**：关闭按钮；可自定义子节点，默认关闭图标。
- **Popover.Title**：可选标题，使用预设排版。
- **Popover.Description**：可选说明文字，弱化样式。
## 用法
### 基础用法
通过组合子部件创建浮动内容面板。
```tsx
<Popover>
<Popover.Trigger>...</Popover.Trigger>
<Popover.Portal>
<Popover.Overlay />
<Popover.Content presentation="popover">...</Popover.Content>
</Popover.Portal>
</Popover>
```
### 标题与说明
使用标题与说明组织内容层级。
```tsx
<Popover>
<Popover.Trigger>...</Popover.Trigger>
<Popover.Portal>
<Popover.Overlay />
<Popover.Content presentation="popover">
<Popover.Close />
<Popover.Title>...</Popover.Title>
<Popover.Description>...</Popover.Description>
</Popover.Content>
</Popover.Portal>
</Popover>
```
### 带箭头
添加指向触发器的箭头以增强视觉关联。
```tsx
<Popover>
<Popover.Trigger>...</Popover.Trigger>
<Popover.Portal>
<Popover.Overlay />
<Popover.Content presentation="popover" placement="top">
<Popover.Arrow />
...
</Popover.Content>
</Popover.Portal>
</Popover>
```
> **说明：** 使用 `<Popover.Arrow />` 时，需要为 `Popover.Content` 添加边框，例如 `border border-border`，以便箭头与内容边框视觉衔接。
### 宽度控制
通过 `width` 控制浮层内容宽度。
```tsx
{
/* 固定像素宽度 */
}
<Popover>
<Popover.Trigger>...</Popover.Trigger>
<Popover.Portal>
<Popover.Overlay />
<Popover.Content presentation="popover" width={320}>
...
</Popover.Content>
</Popover.Portal>
</Popover>;
{
/* 与触发器同宽 */
}
<Popover>
<Popover.Trigger>...</Popover.Trigger>
<Popover.Portal>
<Popover.Overlay />
<Popover.Content presentation="popover" width="trigger">
...
</Popover.Content>
</Popover.Portal>
</Popover>;
{
/* 全宽（100%） */
}
<Popover>
<Popover.Trigger>...</Popover.Trigger>
<Popover.Portal>
<Popover.Overlay />
<Popover.Content presentation="popover" width="full">
...
</Popover.Content>
</Popover.Portal>
</Popover>;
{
/* 随内容自适应（默认） */
}
<Popover>
<Popover.Trigger>...</Popover.Trigger>
<Popover.Portal>
<Popover.Overlay />
<Popover.Content presentation="popover" width="content-fit">
...
</Popover.Content>
</Popover.Portal>
</Popover>;
```
### 底部抽屉呈现
在移动端使用底部抽屉交互。
> **重要：** `Popover.Content` 的 `presentation` 必须与 `Popover` 根上的 `presentation` 一致。开发模式下不一致会抛错。
```tsx
<Popover presentation="bottom-sheet">
<Popover.Trigger>...</Popover.Trigger>
<Popover.Portal>
<Popover.Overlay />
<Popover.Content presentation="bottom-sheet">
<Popover.Title>...</Popover.Title>
<Popover.Description>...</Popover.Description>
<Button>关闭</Button>
</Popover.Content>
</Popover.Portal>
</Popover>
```
### 方位选项
控制浮层相对触发器出现的位置。
```tsx
<Popover>
<Popover.Trigger>...</Popover.Trigger>
<Popover.Portal>
<Popover.Content presentation="popover" placement="left">
...
</Popover.Content>
</Popover.Portal>
</Popover>
```
### 对齐选项
沿放置轴微调内容对齐。
```tsx
<Popover>
<Popover.Trigger>...</Popover.Trigger>
<Popover.Portal>
<Popover.Content presentation="popover" placement="top" align="start">
...
</Popover.Content>
</Popover.Portal>
</Popover>
```
### 自定义动画
在 `Popover` 根上使用 `animation` 配置展开/收起过渡。
```tsx
<Popover
animation={{
entering: {
type: 'spring',
config: { damping: 15, stiffness: 300 },
},
exiting: {
type: 'timing',
config: { duration: 200 },
},
}}
>
<Popover.Trigger>...</Popover.Trigger>
<Popover.Portal>
<Popover.Overlay />
<Popover.Content presentation="popover">...</Popover.Content>
</Popover.Portal>
</Popover>
```
### 编程式控制
```tsx
// 通过 ref 编程式打开/关闭
const popoverRef = useRef<PopoverTriggerRef>(null);
// 打开
popoverRef.current?.open();
// 关闭
popoverRef.current?.close();
// 完整示例
<Popover>
<Popover.Trigger ref={popoverRef} asChild>
<Button>触发器</Button>
</Popover.Trigger>
<Popover.Portal>
<Popover.Overlay />
<Popover.Content presentation="popover">
<Text>内容</Text>
<Button onPress={() => popoverRef.current?.close()}>关闭</Button>
</Popover.Content>
</Popover.Portal>
</Popover>;
```
## 示例
```tsx
import { Ionicons } from '@expo/vector-icons';
import { Button, Popover, useThemeColor } from 'heroui-native';
import { Text, View } from 'react-native';
export default function PopoverExample() {
const themeColorMuted = useThemeColor('muted');
return (
<Popover>
<Popover.Trigger asChild>
<Button variant="tertiary" size="sm">
<Ionicons
name="information-circle"
size={20}
color={themeColorMuted}
/>
<Button.Label>查看说明</Button.Label>
</Button>
</Popover.Trigger>
<Popover.Portal>
<Popover.Overlay />
<Popover.Content
presentation="popover"
width={320}
className="gap-1 rounded-xl px-6 py-4"
>
<Popover.Close className="absolute top-3 right-3 z-50" />
<Popover.Title>说明</Popover.Title>
<Popover.Description>
此浮层包含标题与描述，用于向用户提供更有层次的信息。
</Popover.Description>
</Popover.Content>
</Popover.Portal>
</Popover>
);
}
```
更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/popover.tsx)。
## API 参考
### Popover
| prop | type | default | description |
| --------------- | ----------------------------- | ----------- | ---------------------------------------------------------------------------------------------- |
| `children` | `ReactNode` | - | 浮层内的子节点 |
| `isOpen` | `boolean` | - | 是否展开（受控） |
| `isDefaultOpen` | `boolean` | - | 初始是否展开（非受控） |
| `onOpenChange` | `(isOpen: boolean) => void` | - | 展开状态变化时的回调 |
| `animation` | `AnimationRootDisableAll` | - | 动画配置，可为 `false`、`"disabled"`、`"disable-all"`、`true` 或 `undefined` |
| `presentation` | `'popover' \| 'bottom-sheet'` | `'popover'` | 内容呈现方式 |
| `asChild` | `boolean` | `false` | 是否将子元素作为实际渲染节点 |
| `...ViewProps` | `ViewProps` | - | 支持全部标准 React Native `View` 属性 |
#### AnimationRootDisableAll
根级动画配置，可为：
- `false` 或 `"disabled"`：仅禁用根动画
- `"disable-all"`：禁用根与子级全部动画
- `true` 或 `undefined`：使用默认动画
### Popover.Trigger
| prop | type | default | description |
| ------------------- | ---------------- | ------- | ------------------------------------------------------- |
| `children` | `ReactNode` | - | 触发器内容 |
| `className` | `string` | - | 触发器额外 class |
| `asChild` | `boolean` | `true` | 是否将子元素作为实际渲染节点 |
| `...PressableProps` | `PressableProps` | - | 支持全部标准 React Native `Pressable` 属性 |
### Popover.Portal
| prop | type | default | description |
| -------------------------- | ----------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `children` | `ReactNode` | - | Portal内容（必填） |
| `disableFullWindowOverlay` | `boolean` | `false` | 在 iOS 为 `true` 时使用 `View` 代替 `FullWindowOverlay`，便于元素检查器；遮罩将无法叠在原生模态之上 |
| `unstable_accessibilityContainerViewIsModal` | `boolean` | `false` | 控制 VoiceOver 是否将遮罩窗口视为模态容器。为 `true` 时，VoiceOver 仅聚焦遮罩内元素。仅 iOS；API 不稳定，可能随 react-native-screens 变更 |
| `hostName` | `string` | - | Portal宿主元素的可选名称 |
| `forceMount` | `boolean` | - | 是否强制挂载 |
| `className` | `string` | - | Portal容器额外 class |
| `...ViewProps` | `ViewProps` | - | 支持全部标准 React Native `View` 属性 |
### Popover.Overlay
| prop | type | default | description |
| ----------------------- | ------------------------- | ------- | ------------------------------------------------------------ |
| `className` | `string` | - | 遮罩额外 class |
| `closeOnPress` | `boolean` | `true` | 点击遮罩是否关闭 |
| `forceMount` | `boolean` | - | 是否强制挂载 |
| `animation` | `PopoverOverlayAnimation` | - | 动画配置 |
| `isAnimatedStyleActive` | `boolean` | `true` | 是否启用 Reanimated 动画样式 |
| `asChild` | `boolean` | `false` | 是否将子元素作为实际渲染节点 |
| `...Animated.ViewProps` | `Animated.ViewProps` | - | 支持 Reanimated `Animated.View` 的全部属性 |
#### PopoverOverlayAnimation
遮罩动画配置，可为：
- `false` 或 `"disabled"`：禁用全部动画
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| --------------- | -------------------------- | --------------------------- | ----------------------------------------------------------------------------------------- |
| `state` | `'disabled' \| boolean` | - | 在自定义属性时用于禁用动画 |
| `opacity.value` | `[number, number, number]` | `[0, 1, 0]` | 透明度 [空闲, 打开, 关闭]，用于底部抽屉等呈现 |
| `entering` | `EntryOrExitLayoutType` | 默认淡入 200ms | 自定义进入关键帧，用于 `popover` 呈现 |
| `exiting` | `EntryOrExitLayoutType` | 默认淡出 150ms | 自定义退出关键帧，用于 `popover` 呈现 |
### Popover.Content（Popover 呈现）
| prop | type | default | description |
| ------------------------- | ------------------------------------------------ | --------------- | ------------------------------------------------------------------------------------------------------- |
| `children` | `ReactNode` | - | 浮层内容 |
| `presentation` | `'popover'` | `'popover'` | 呈现模式，须与 `Popover` 根一致；未传时默认为 `popover` |
| `width` | `number \| 'trigger' \| 'content-fit' \| 'full'` | `'content-fit'` | 内容宽度策略 |
| `placement` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | 相对触发器的方位 |
| `align` | `'start' \| 'center' \| 'end'` | `'center'` | 沿放置轴的对齐 |
| `avoidCollisions` | `boolean` | `true` | 靠近视口边缘时是否翻转 placement |
| `offset` | `number` | `9` | 与触发器的间距（像素） |
| `alignOffset` | `number` | `0` | 沿对齐轴的偏移（像素） |
| `disablePositioningStyle` | `boolean` | `false` | 是否禁用自动定位样式 |
| `forceMount` | `boolean` | - | 是否强制挂载 |
| `insets` | `Insets` | - | 定位时需遵守的屏幕边距 |
| `className` | `string` | - | 内容容器额外 class |
| `animation` | `PopupPopoverContentAnimation` | - | 动画配置 |
| `isAnimatedStyleActive` | `boolean` | `true` | 是否启用 Reanimated 动画样式 |
| `asChild` | `boolean` | `false` | 是否将子元素作为实际渲染节点 |
| `...Animated.ViewProps` | `Animated.ViewProps` | - | 支持 Reanimated `Animated.View` 的全部属性 |
### Popover.Content（底部抽屉呈现）
| prop | type | default | description |
| --------------------------- | ---------------------- | ------- | ---------------------------------------------------------------------------------------------- |
| `children` | `ReactNode` | - | 底部抽屉内容 |
| `presentation` | `'bottom-sheet'` | - | 呈现模式，须为 `bottom-sheet` 并与根一致（必填） |
| `contentContainerClassName` | `string` | - | 内容容器额外 class |
| `contentContainerProps` | `BottomSheetViewProps` | - | 内容容器属性 |
| `enablePanDownToClose` | `boolean` | `true` | 是否允许下滑关闭 |
| `backgroundStyle` | `ViewStyle` | - | 底部抽屉背景样式 |
| `handleIndicatorStyle` | `ViewStyle` | - | 把手指示器样式 |
| `...BottomSheetProps` | `BottomSheetProps` | - | 支持 `@gorhom/bottom-sheet` 的全部属性 |
#### PopupPopoverContentAnimation
内容（`popover` 呈现）动画配置，可为：
- `false` 或 `"disabled"`：禁用全部动画
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| ---------- | ----------------------- | --------------------------------------------------------------- | ------------------------------------------------- |
| `state` | `'disabled' \| boolean` | - | 在自定义属性时用于禁用动画 |
| `entering` | `EntryOrExitLayoutType` | 默认关键帧：translateY/translateX、scale、opacity（200ms） | 自定义进入关键帧 |
| `exiting` | `EntryOrExitLayoutType` | 默认与进入镜像（150ms） | 自定义退出关键帧 |
### Popover.Arrow
| prop | type | default | description |
| --------------------- | ---------------------------------------- | ------- | --------------------------------------------------------------------- |
| `className` | `string` | - | 箭头额外 class |
| `height` | `number` | `12` | 箭头高度（像素） |
| `width` | `number` | `20` | 箭头宽度（像素） |
| `fill` | `string` | - | 填充色（默认与内容背景一致） |
| `stroke` | `string` | - | 描边色（默认与内容边框色一致） |
| `strokeWidth` | `number` | `1` | 描边宽度（像素） |
| `strokeBaselineInset` | `number` | `1` | 描边基线内缩（像素） |
| `placement` | `'top' \| 'bottom' \| 'left' \| 'right'` | - | 浮层方位（自内容继承） |
| `children` | `ReactNode` | - | 自定义箭头内容（替换默认 SVG） |
| `style` | `StyleProp<ViewStyle>` | - | 箭头容器额外样式 |
| `...ViewProps` | `ViewProps` | - | 支持全部标准 React Native `View` 属性 |
### Popover.Close
`Popover.Close` 继承 [CloseButton](./close-button)，按下时自动关闭浮层。
### Popover.Title
| prop | type | default | description |
| -------------- | ----------- | ------- | -------------------------------------------------- |
| `children` | `ReactNode` | - | 标题文案 |
| `className` | `string` | - | 标题额外 class |
| `...TextProps` | `TextProps` | - | 支持全部标准 React Native `Text` 属性 |
### Popover.Description
| prop | type | default | description |
| -------------- | ----------- | ------- | -------------------------------------------------- |
| `children` | `ReactNode` | - | 说明文案 |
| `className` | `string` | - | 说明额外 class |
| `...TextProps` | `TextProps` | - | 支持全部标准 React Native `Text` 属性 |
## Hooks
### usePopover
在自定义或复合子组件中读取浮层上下文。
```tsx
import { usePopover } from 'heroui-native';
const CustomContent = () => {
const { isOpen, onOpenChange, triggerPosition } = usePopover();
// …实现
};
```
#### 返回值
| property | type | description |
| -------------------- | --------------------------------------------------- | ----------------------------------------------------------------- |
| `isOpen` | `boolean` | 当前是否打开 |
| `onOpenChange` | `(open: boolean) => void` | 修改展开状态的回调 |
| `isDefaultOpen` | `boolean \| undefined` | 默认是否打开（非受控） |
| `isDisabled` | `boolean \| undefined` | 是否禁用 |
| `triggerPosition` | `LayoutPosition \| null` | 触发器相对视口的位置 |
| `setTriggerPosition` | `(triggerPosition: LayoutPosition \| null) => void` | 更新触发器位置 |
| `contentLayout` | `LayoutRectangle \| null` | 浮层内容的布局测量 |
| `setContentLayout` | `(contentLayout: LayoutRectangle \| null) => void` | 更新内容布局测量 |
| `nativeID` | `string` | 当前实例唯一标识 |
**说明：** 必须在 `Popover` 内使用；在上下文外调用将抛错。
### usePopoverAnimation
在自定义或复合子组件中读取浮层动画共享值。
```tsx
import { usePopoverAnimation } from 'heroui-native';
const CustomContent = () => {
const { progress, isDragging } = usePopoverAnimation();
// …实现
};
```
#### 返回值
| property | type | description |
| ------------ | ---------------------- | ------------------------------------------------------------------ |
| `progress` | `SharedValue<number>` | 动画进度（0=空闲，1=打开，2=关闭） |
| `isDragging` | `SharedValue<boolean>` | 是否正在拖拽 |
**说明：** 必须在 `Popover` 内使用；在动画上下文外调用将抛错。
## 特别说明
### 元素检查器（iOS）
`Popover` 在 iOS 使用 `FullWindowOverlay`。开发时若需启用 React Native 元素检查器，可在 `Popover.Portal` 设置 `disableFullWindowOverlay={true}`。代价：浮层将无法叠在原生系统模态之上。
### 原生模态（iOS）
当 `Popover` 位于以原生模态形式呈现的页面内时（`presentation: 'modal' | 'formSheet' | 'pageSheet'`），浮层内容可能会向上偏移渲染。在新架构（Fabric）中，`react-native-screens` 将 `RNSModalScreen` 标记为 Fabric 根节点，因此触发器的坐标是相对于模态原点上报的，而 `FullWindowOverlay`（浮层挂载点）锚定在 iOS 应用窗口上。可通过将 `safeAreaInsets.top` 加到 `offset` 来补偿：
```tsx
import { useSafeAreaInsets } from 'react-native-safe-area-context';
const insets = useSafeAreaInsets();
<Popover.Content presentation="popover" offset={insets.top + 20}>
...
</Popover.Content>;
```
apps/docs/content/docs/cn/native/components/(overlays)/toast.mdx
+431
View File
@@ -0,0 +1,431 @@
---
title: Toast 轻提示
description: 在屏幕顶部或底部展示的临时通知消息。
links:
source_native: toast/toast.tsx
styles_native: toast/toast.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/toast-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/toast-docs-dark.mp4"
/>
## 导入
```tsx
import { Toast, useToast } from 'heroui-native';
```
## 结构
```tsx
<Toast>
<Toast.Title>...</Toast.Title>
<Toast.Description>...</Toast.Description>
<Toast.Action>...</Toast.Action>
<Toast.Close />
</Toast>
```
- **Toast**：主容器，负责定位、动画与滑动手势。
- **Toast.Title**：标题文字，继承父级 Toast 的变体样式。
- **Toast.Description**：标题下方的描述文字。
- **Toast.Action**：操作按钮；按钮变体默认随 Toast 变体推断，也可覆盖。
- **Toast.Close**：关闭按钮，图标按钮样式，按下时调用隐藏。
## 用法
### 用法一：简单字符串
使用纯字符串快速展示 Toast。
```tsx
const { toast } = useToast();
toast.show('这是一条 Toast 消息');
```
### 用法二：配置对象
通过配置对象传入标题、描述、变体与操作按钮等。
```tsx
const { toast } = useToast();
toast.show({
variant: 'success',
label: '套餐已升级',
description: '可继续使用 HeroUI Chat',
icon: <Icon name="check" />,
actionLabel: '关闭',
onActionPress: ({ hide }) => hide(),
});
```
### 用法三：自定义组件
使用完全自定义的组件以自由控制样式与布局。
```tsx
const { toast } = useToast();
toast.show({
component: (props) => (
<Toast variant="accent" placement="top" {...props}>
<Toast.Title>自定义 Toast</Toast.Title>
<Toast.Description>这是一个自定义 Toast 组件</Toast.Description>
<Toast.Close />
</Toast>
),
});
```
**说明**：Toast 条目会做性能相关的 memo。若需把外部状态（如加载中）传入自定义 Toast，不会自动随状态重渲染。请使用 React Context、全局状态或 ref 等方式让状态能传递到 Toast 内。
### 禁用全部动画
使用 `"disable-all"` 可禁用自身及子级（如 `Toast.Action` 内的 `Button`）的全部动画。
```tsx
const { toast } = useToast();
toast.show({
variant: 'success',
label: '操作完成',
description: '已禁用全部动画',
animation: 'disable-all',
});
```
自定义组件示例：
```tsx
const { toast } = useToast();
toast.show({
component: (props) => (
<Toast variant="accent" animation="disable-all" {...props}>
<Toast.Title>无动画</Toast.Title>
<Toast.Description>
此 Toast 已禁用全部动画
</Toast.Description>
<Toast.Action>操作</Toast.Action>
</Toast>
),
});
```
## 示例
```tsx
import { Button, Toast, useToast, useThemeColor } from 'heroui-native';
import { View } from 'react-native';
export default function ToastExample() {
const { toast } = useToast();
const themeColorForeground = useThemeColor('foreground');
return (
<View className="gap-4 p-4">
<Button
onPress={() =>
toast.show({
variant: 'success',
label: '套餐已升级',
description: '可继续使用 HeroUI Chat',
actionLabel: '关闭',
onActionPress: ({ hide }) => hide(),
})
}
>
显示成功 Toast
</Button>
<Button
onPress={() =>
toast.show({
component: (props) => (
<Toast variant="accent" {...props}>
<Toast.Title>自定义 Toast</Toast.Title>
<Toast.Description>
使用自定义组件渲染
</Toast.Description>
<Toast.Action onPress={() => props.hide()}>撤销</Toast.Action>
<Toast.Close className="absolute top-0 right-0" />
</Toast>
),
})
}
>
显示自定义 Toast
</Button>
</View>
);
}
```
更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/toast.tsx>)。
## 全局配置
通过 `HeroUINativeProvider` 的 `config` 全局配置 Toast；本地调用可覆盖默认值。
> **说明**：Provider 的完整配置见 [Provider 文档](/docs/native/getting-started/handbook/provider#toast-configuration)。
### 边距（Insets）
控制 Toast 与屏幕边缘的距离，会在安全区内边距基础上叠加。例如四边距屏幕 20px：
```tsx
<HeroUINativeProvider
config={{
toast: {
insets: {
top: 20,
bottom: 20,
left: 20,
right: 20,
},
},
}}
>
{children}
</HeroUINativeProvider>
```
### 使用 KeyboardAvoidingView 包裹内容
用 `KeyboardAvoidingView` 包裹 Toast 内容，键盘弹出时自动避让：
```tsx
import {
KeyboardAvoidingView,
KeyboardProvider,
} from 'react-native-keyboard-controller';
import { HeroUINativeProvider } from 'heroui-native';
import { useCallback } from 'react';
function AppContent() {
const contentWrapper = useCallback(
(children: React.ReactNode) => (
<KeyboardAvoidingView
pointerEvents="box-none"
behavior="padding"
keyboardVerticalOffset={12}
className="flex-1"
>
{children}
</KeyboardAvoidingView>
),
[]
);
return (
<KeyboardProvider>
<HeroUINativeProvider
config={{
toast: {
contentWrapper,
},
}}
>
{children}
</HeroUINativeProvider>
</KeyboardProvider>
);
}
```
### 默认属性
全局设置变体、位置、动画与滑动等默认值：
```tsx
<HeroUINativeProvider
config={{
toast: {
defaultProps: {
variant: 'accent',
placement: 'bottom',
isSwipeable: false,
},
},
}}
>
{children}
</HeroUINativeProvider>
```
## API 参考
### Toast
| prop | type | default | description |
| ----------------------- | ------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------- |
| `variant` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'default'` | 视觉变体 |
| `placement` | `'top' \| 'bottom'` | `'top'` | 在屏幕上的位置 |
| `isSwipeable` | `boolean` | `true` | 是否可滑动关闭并带橡皮筋拖拽效果 |
| `animation` | `ToastRootAnimation` | - | 动画配置 |
| `isAnimatedStyleActive` | `boolean` | `true` | 是否启用 Reanimated 动画样式 |
| `className` | `string` | - | Toast 容器额外 class |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部属性 |
#### ToastRootAnimation
Toast 根动画配置，可为：
- `false` 或 `"disabled"`：仅禁用根级动画
- `"disable-all"`：禁用全部动画（含子级）
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| ------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `state` | `'disabled' \| 'disable-all' \| boolean` | - | 在自定义属性时禁用动画 |
| `opacity.value` | `[number, number]` | `[1, 0]` | Toast 移出可视堆叠时的透明度插值 |
| `opacity.timingConfig` | `WithTimingConfig` | `{ duration: 300 }` | 透明度过渡的时间配置 |
| `translateY.value` | `[number, number]` | `[0, 10]` | 堆叠 Toast 微位移效果的 Y 插值 |
| `translateY.timingConfig` | `WithTimingConfig` | `{ duration: 300 }` | translateY 过渡的时间配置 |
| `scale.value` | `[number, number]` | `[1, 0.97]` | 堆叠 Toast 景深缩放的插值 |
| `scale.timingConfig` | `WithTimingConfig` | `{ duration: 300 }` | 缩放过渡的时间配置 |
| `entering.top` | `EntryOrExitLayoutType` | `FadeInUp`<br/>`.springify()`<br/>`.withInitialValues({ opacity: 1, transform: [{ translateY: -100 }] })`<br/>`.mass(3)` | 顶部放置时的进入动画 |
| `entering.bottom` | `EntryOrExitLayoutType` | `FadeInDown`<br/>`.springify()`<br/>`.withInitialValues({ opacity: 1, transform: [{ translateY: 100 }] })`<br/>`.mass(3)` | 底部放置时的进入动画 |
| `exiting.top` | `EntryOrExitLayoutType` | 关键帧动画<br/>`translateY: -100, scale: 0.97, opacity: 0.5` | 顶部放置时的退出动画 |
| `exiting.bottom` | `EntryOrExitLayoutType` | 关键帧动画<br/>`translateY: 100, scale: 0.97, opacity: 0.5` | 底部放置时的退出动画 |
### Toast.Title
| prop | type | default | description |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | - | 标题内容 |
| `className` | `string` | - | 额外的 class |
| `...TextProps` | `TextProps` | - | 支持 React Native `Text` 的全部属性 |
### Toast.Description
| prop | type | default | description |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children` | `React.ReactNode` | - | 描述内容 |
| `className` | `string` | - | 额外的 class |
| `...TextProps` | `TextProps` | - | 支持 React Native `Text` 的全部属性 |
### Toast.Action
`Toast.Action` 继承 [Button](button) 的全部属性。按钮变体默认由 Toast 变体推断，也可覆盖。
| prop | type | default | description |
| ----------- | ---------------------- | ------- | ---------------------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 操作按钮文字 |
| `variant` | `ButtonVariant` | - | 按钮变体；未提供时由 Toast 变体自动决定 |
| `size` | `'sm' \| 'md' \| 'lg'` | `'sm'` | 操作按钮尺寸 |
| `className` | `string` | - | 额外的 class |
`onPress`、`isDisabled` 等其余属性见 [Button API 参考](button#api-reference)。
### Toast.Close
`Toast.Close` 继承 [Button](button) 的全部属性。
| prop | type | default | description |
| ----------- | ----------------------------------- | ------- | ---------------------------------------------- |
| `children` | `React.ReactNode` | - | 自定义关闭图标；默认使用 CloseIcon |
| `iconProps` | `{ size?: number; color?: string }` | - | 默认关闭图标的属性 |
| `size` | `'sm' \| 'md' \| 'lg'` | `'sm'` | 关闭按钮尺寸 |
| `className` | `string` | - | 额外的 class |
| `onPress` | `(event: any) => void` | - | 自定义按下处理；默认隐藏 Toast |
其余继承属性见 [Button API 参考](button#api-reference)。
### ToastProviderProps
通过 `HeroUINativeProvider` 的 `config.toast` 进行全局配置时可用的属性。
| prop | type | default | description |
| -------------------------------------------- | --------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `defaultProps` | `ToastGlobalConfig` | - | 全局默认配置，可被单次调用覆盖 |
| `disableFullWindowOverlay` | `boolean` | `false` | iOS 上为 true 时使用普通 `View` 替代 `FullWindowOverlay`，便于元素检查器；Toast 将不再叠在原生模态之上 |
| `unstable_accessibilityContainerViewIsModal` | `boolean` | `false` | 是否将覆盖窗口视为模态容器（VoiceOver）。为 true 时焦点限制在覆盖层内。仅 iOS；可能随 react-native-screens 变化 |
| `insets` | `ToastInsets` | - | 相对屏幕边缘的内边距（与安全区内边距相加） |
| `maxVisibleToasts` | `number` | `3` | 最大可见条数，超过后开始降低透明度 |
| `contentWrapper` | `(children: React.ReactNode) => React.ReactElement` | - | 自定义包裹 Toast 内容的函数 |
| `children` | `React.ReactNode` | - | 子节点 |
#### ToastGlobalConfig
全局默认，可被单次调用覆盖。
| prop | type | description |
| ------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `variant` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | 视觉变体 |
| `placement` | `'top' \| 'bottom'` | 位置 |
| `isSwipeable` | `boolean` | 是否可滑动关闭并带橡皮筋效果 |
| `animation` | `ToastRootAnimation` | Toast 动画配置 |
#### ToastInsets
相对屏幕边缘的间距，会与安全区内边距相加。
| prop | type | default | description |
| -------- | -------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `top` | `number` | - | 距顶部像素（叠加安全区）。平台默认：iOS 0，Android 12 |
| `bottom` | `number` | - | 距底部像素（叠加安全区）。平台默认：iOS 6，Android 12 |
| `left` | `number` | - | 距左侧像素（叠加安全区）。默认 12 |
| `right` | `number` | - | 距右侧像素（叠加安全区）。默认 12 |
## Hooks
### useToast
访问 Toast 能力，必须在 `ToastProvider` 内使用（由 `HeroUINativeProvider` 提供）。
| 返回值 | type | description |
| ---------------- | -------------- | ---------------------------------------- |
| `toast` | `ToastManager` | 含 `show`、`hide` 等方法的 Toast 管理器 |
| `isToastVisible` | `boolean` | 当前是否有 Toast 可见 |
#### ToastManager
| method | type | description |
| ------ | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `show` | `(options: string \| ToastShowOptions) => string` | 显示 Toast，返回 ID。支持字符串、配置对象或自定义组件三种形式 |
| `hide` | `(ids?: string \| string[] \| 'all') => void` | 隐藏一条或多条。无参隐藏最后一条；`'all'` 隐藏全部；传入 ID 或 ID 数组隐藏指定项 |
#### ToastShowOptions
展示选项：默认样式的配置对象，或自定义组件。
**使用配置对象（无 `component`）时：**
| prop | type | default | description |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------- |
| `variant` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | - | 视觉变体 |
| `placement` | `'top' \| 'bottom'` | - | 位置 |
| `isSwipeable` | `boolean` | - | 是否可滑动关闭 |
| `animation` | `ToastRootAnimation \| false \| "disabled" \| "disable-all"` | - | 动画配置 |
| `duration` | `number \| 'persistent'` | `4000` | 自动隐藏毫秒数；`'persistent'` 表示不自动隐藏 |
| `id` | `string` | - | 可选 ID；未提供则自动生成 |
| `label` | `string` | - | 标题文字 |
| `description` | `string` | - | 描述文字 |
| `actionLabel` | `string` | - | 操作按钮文案 |
| `onActionPress` | `(helpers: { show: (options: string \| ToastShowOptions) => string; hide: (ids?: string \| string[] \| 'all') => void }) => void` | - | 操作按钮按下回调 |
| `icon` | `React.ReactNode` | - | 左侧图标 |
| `onShow` | `() => void` | - | 显示时回调 |
| `onHide` | `() => void` | - | 隐藏时回调 |
**使用自定义组件时：**
| prop | type | default | description |
| ----------- | ---------------------------------------------------- | ------- | ----------------------------------------------------------------------------------- |
| `id` | `string` | - | 可选 ID；未提供则自动生成 |
| `component` | `(props: ToastComponentProps) => React.ReactElement` | - | 接收 Toast props 并返回 React 元素的函数 |
| `duration` | `number \| 'persistent'` | `4000` | 自动隐藏毫秒数；`'persistent'` 表示不自动隐藏 |
| `onShow` | `() => void` | - | 显示时回调 |
| `onHide` | `() => void` | - | 隐藏时回调 |
## 特别说明
### 元素检查器（iOS）
Toast 在 iOS 上使用 `FullWindowOverlay`。开发时若需使用 React Native 元素检查器，可在 `HeroUINativeProvider` 的 `config.toast` 中设置 `disableFullWindowOverlay={true}`。代价：Toast 将无法叠在原生系统模态之上。
apps/docs/content/docs/cn/native/components/(typography)/text.mdx
+220
View File
@@ -0,0 +1,220 @@
---
title: Typography 文本
description: 用于渲染带语义类型变体的样式化文本的排版基元组件。
icon: updated
links:
source_native: text/text.tsx
styles_native: text/text.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/text-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/text-docs-dark.mp4"
/>
## 导入
```tsx
import { Typography } from 'heroui-native';
```
## 结构
```tsx
<Typography>...</Typography>
{/* 子组件 */}
<Typography.Heading>...</Typography.Heading>
<Typography.Paragraph>...</Typography.Paragraph>
<Typography.Code>...</Typography.Code>
```
- **Typography**：文本根元素。通过 `type` 选择排版预设，并提供互不耦合的 `align`、`color`、`weight`、`truncate` 属性。
- **Typography.Heading**：限定为标题类型（`h1`–`h6`）的便捷包装组件，会自动添加 `accessibilityRole="header"`。
- **Typography.Paragraph**：限定为正文类型（`body`、`body-sm`、`body-xs`）的便捷包装组件。
- **Typography.Code**：以 chip 样式呈现的等宽内联文本，采用平台合适的等宽字体。
## 用法
### 基础用法
`Typography` 默认渲染正文文本。
```tsx
<Typography>Hello, world!</Typography>
```
### 类型变体
使用 `type` 属性选择语义化排版预设。
```tsx
<Typography type="h1">Heading 1</Typography>
<Typography type="h2">Heading 2</Typography>
<Typography type="h3">Heading 3</Typography>
<Typography type="h4">Heading 4</Typography>
<Typography type="h5">Heading 5</Typography>
<Typography type="h6">Heading 6</Typography>
<Typography type="body">Body text</Typography>
<Typography type="body-sm">Small body text</Typography>
<Typography type="body-xs">Extra-small body text</Typography>
<Typography type="code">Code snippet</Typography>
```
### 标题
使用 `Typography.Heading` 渲染标题文本，自动具备 header 无障碍角色。
```tsx
<Typography.Heading type="h1">Page Title</Typography.Heading>
<Typography.Heading type="h2">Section Title</Typography.Heading>
<Typography.Heading type="h3">Subsection Title</Typography.Heading>
```
### 段落
使用 `Typography.Paragraph` 渲染正文文本。
```tsx
<Typography.Paragraph>
这是一个使用默认尺寸渲染的正文段落。
</Typography.Paragraph>
<Typography.Paragraph type="body-sm">
这是较小的正文文本。
</Typography.Paragraph>
```
### 代码
使用 `Typography.Code`（或等价的 `<Typography type="code">`）渲染内联代码片段。两者都会呈现为 chip 样式的等宽内联元素，带有低饱和背景、圆角，并采用 `self-start` 布局以避免在 flex 容器中被拉伸。平台相关的等宽 `fontFamily` 在 `Typography` 根元素上应用，因此两种写法可互换。
```tsx
<Typography.Code>console.log('hello')</Typography.Code>
<Typography type="code">console.log('hello')</Typography>
```
### 对齐
使用 `align` 属性控制水平对齐。`start` 与 `end` 是 RTL 感知的（在从右到左布局下会翻转）。
```tsx
<Typography align="start">Start-aligned</Typography>
<Typography align="center">Center-aligned</Typography>
<Typography align="end">End-aligned</Typography>
<Typography align="justify">Justified text spreads across the line.</Typography>
```
> **说明：** `text-justify` 在 React Native 中仅 iOS 生效；Android 会回退为左对齐。
### 颜色
使用 `color` 属性应用语义化前景色预设。
```tsx
<Typography color="default">Default foreground</Typography>
<Typography color="muted">Muted secondary text</Typography>
```
如需其他主题色，可通过 `className` 传入对应工具类（如 `className="text-accent"`、`className="text-danger"`）。
### 字重
使用 `weight` 属性覆盖由 `type` 推导出的字重。该覆盖通过 `tailwind-merge` 合并，因此始终优先于 type 变体的默认字重。
```tsx
<Typography type="h1" weight="bold">Bold H1</Typography>
<Typography weight="medium">Medium body</Typography>
<Typography weight="semibold">Semibold body</Typography>
```
### 截断
使用布尔属性 `truncate` 将文本限制为单行并以省略号结尾。它映射到 React Native 的 `numberOfLines={1}`。如显式提供 `numberOfLines`，则以后者为准。
```tsx
<Typography truncate>
当内容溢出容器时，这一长行文本会被截断并显示省略号。
</Typography>;
{
/* 通过底层 RN 属性实现多行截断 */
}
<Typography numberOfLines={2}>
通过 React Native 标准的 `numberOfLines` 属性可实现多行截断。
</Typography>;
```
## 示例
```tsx
import { Typography } from 'heroui-native';
import { View } from 'react-native';
export default function TypographyExample() {
return (
<View className="flex-1 justify-center px-5 gap-4">
<Typography.Heading type="h1">欢迎</Typography.Heading>
<Typography.Heading type="h3">快速开始</Typography.Heading>
<Typography.Paragraph>
这是使用 Typography 组件渲染的正文段落。
</Typography.Paragraph>
<Typography.Paragraph color="muted" type="body-sm">
用于注释或脚注的较小辅助文本。
</Typography.Paragraph>
<Typography.Code>npm install heroui-native</Typography.Code>
</View>
);
}
```
更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/text.tsx>)。
## API 参考
### Typography
`Typography` 继承 React Native 的全部 `TextProps`，并新增排版相关属性。
| prop | type | default | description |
| -------------- | -------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------- |
| `type` | `'h1' \| 'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6' \| 'body' \| 'body-sm' \| 'body-xs' \| 'code'` | `'body'` | 语义化排版变体（字号、默认字重、行高） |
| `align` | `'start' \| 'center' \| 'end' \| 'justify'` | `'start'` | 水平对齐方式。`start` 与 `end` 为 RTL 感知；`justify` 仅 iOS 生效 |
| `color` | `'default' \| 'muted'` | `'default'` | 语义化前景色预设 |
| `weight` | `'normal' \| 'medium' \| 'semibold' \| 'bold'` | - | 字重覆盖。设置后会覆盖 `type` 暗含的字重 |
| `truncate` | `boolean` | `false` | 将文本截断为单行并显示省略号（即设 `numberOfLines={1}`）。显式 `numberOfLines` 优先级更高 |
| `children` | `React.ReactNode` | - | 渲染内容 |
| `className` | `string` | - | 额外 CSS 类 |
| `...TextProps` | `TextProps` | - | 支持 React Native `Text` 的全部标准属性 |
### Typography.Heading
继承 `Typography` 根元素的全部属性（`align`、`color`、`weight`、`truncate`、`className` 及 React Native `TextProps`）。自动设置 `accessibilityRole="header"`，并将 `type` 收窄为标题变体。
| prop | type | default | description |
| -------------- | ---------------------------------------------- | ------- | ---------------------------------------- |
| `type` | `'h1' \| 'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'` | `'h1'` | 标题级别 |
| `children` | `React.ReactNode` | - | 渲染内容 |
| `className` | `string` | - | 额外 CSS 类 |
| `...TextProps` | `TextProps` | - | 支持 React Native `Text` 的全部标准属性 |
### Typography.Paragraph
继承 `Typography` 根元素的全部属性（`align`、`color`、`weight`、`truncate`、`className` 及 React Native `TextProps`）。将 `type` 收窄为正文变体。
| prop | type | default | description |
| -------------- | ---------------------------------- | -------- | ---------------------------------------- |
| `type` | `'body' \| 'body-sm' \| 'body-xs'` | `'body'` | 段落文本字号 |
| `children` | `React.ReactNode` | - | 渲染内容 |
| `className` | `string` | - | 额外 CSS 类 |
| `...TextProps` | `TextProps` | - | 支持 React Native `Text` 的全部标准属性 |
### Typography.Code
继承 `Typography` 根元素的全部属性（`align`、`color`、`weight`、`truncate`、`className`、`style` 及 React Native `TextProps`）。它是一个强制 `type="code"` 的轻量包装；平台相关的等宽 `fontFamily` 在 `Typography` 根元素上合并，因此 `<Typography type="code">` 与 `<Typography.Code>` 渲染效果完全一致。
| prop | type | default | description |
| -------------- | ----------------- | ------- | ---------------------------------------- |
| `children` | `React.ReactNode` | - | 渲染内容 |
| `className` | `string` | - | 额外 CSS 类 |
| `...TextProps` | `TextProps` | - | 支持 React Native `Text` 的全部标准属性 |
apps/docs/content/docs/cn/native/components/(utilities)/pressable-feedback.mdx
+340
View File
@@ -0,0 +1,340 @@
---
title: PressableFeedback 按压反馈
description: 为按压交互提供视觉反馈的容器组件，内置缩放动画。
icon: updated
links:
source_native: pressable-feedback/pressable-feedback.tsx
styles_native: pressable-feedback/pressable-feedback.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/pressable-feedback-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/pressable-feedback-docs-dark.mp4"
/>
## 导入
```tsx
import { PressableFeedback } from 'heroui-native';
```
## 结构
```tsx
<PressableFeedback>
<PressableFeedback.Highlight />
<PressableFeedback.Ripple />
<PressableFeedback.Scale>...</PressableFeedback.Scale>
</PressableFeedback>
```
- **PressableFeedback**：内置缩放动画的可按压容器；管理按压状态与容器尺寸，并通过上下文提供给子复合部件。使用 `PressableFeedback.Scale` 时可将 `animation={false}` 关闭根级内置缩放。
- **PressableFeedback.Scale**：对特定子元素应用缩放的包装层；需要精确控制哪个元素缩放，或要在缩放层上直接应用 `className` / `style` 时使用。
- **PressableFeedback.Highlight**：iOS 风格的高亮遮罩，绝对定位，在按压时淡入。
- **PressableFeedback.Ripple**：Android 风格的涟漪，从触点扩展的径向渐变圆。
## 用法
### 基础
默认提供按下缩放反馈，多数场景推荐直接使用。
```tsx
<PressableFeedback>...</PressableFeedback>
```
### 配合 Highlight
在默认缩放之外叠加 iOS 风格高亮。
```tsx
<PressableFeedback>
<PressableFeedback.Highlight />
...
</PressableFeedback>
```
### 配合 Ripple
在默认缩放之外叠加 Android 风格涟漪。
```tsx
<PressableFeedback>
<PressableFeedback.Ripple />
...
</PressableFeedback>
```
### 自定义缩放动画
通过根组件 `animation.scale` 配置，支持 `value`、`timingConfig`、`ignoreScaleCoefficient`。
```tsx
<PressableFeedback
animation={{
scale: {
value: 0.9,
timingConfig: { duration: 150 },
ignoreScaleCoefficient: true,
},
}}
>
...
</PressableFeedback>
```
### 自定义 Highlight 动画
配置高亮层的不透明度与背景色。
```tsx
<PressableFeedback>
<PressableFeedback.Highlight
animation={{
backgroundColor: { value: '#3b82f6' },
opacity: { value: [0, 0.2] },
}}
/>
...
</PressableFeedback>
```
### 自定义 Ripple 动画
配置涟漪颜色、不透明度与时长。
```tsx
<PressableFeedback>
<PressableFeedback.Ripple
animation={{
backgroundColor: { value: '#ec4899' },
opacity: { value: [0, 0.1, 0] },
progress: { baseDuration: 600 },
}}
/>
...
</PressableFeedback>
```
### 对指定子元素缩放（PressableFeedback.Scale）
需要对容器内某一子元素而非根节点缩放时，将根组件设为 `animation={false}` 关闭内置缩放，再使用 `PressableFeedback.Scale`，以便在缩放层上直接应用 `className` / `style`。
```tsx
<PressableFeedback animation={false}>
<PressableFeedback.Scale>...</PressableFeedback.Scale>
</PressableFeedback>
```
可与 `Highlight` 或 `Ripple` 组合在 `Scale` 内：
```tsx
<PressableFeedback animation={false}>
<PressableFeedback.Scale>
<PressableFeedback.Highlight />
...
</PressableFeedback.Scale>
</PressableFeedback>
```
### 禁用全部动画
根上设置 `animation="disable-all"` 可级联禁用内置缩放及子复合部件（Scale、Highlight、Ripple）的动画。
```tsx
<PressableFeedback animation="disable-all">...</PressableFeedback>
```
也可在保留缩放配置的同时禁用动画（例如运行时切换）：
```tsx
<PressableFeedback animation={{ scale: { value: 0.97 }, state: 'disable-all' }}>
...
</PressableFeedback>
```
## 示例
```tsx
import { PressableFeedback, Card, Button } from 'heroui-native';
import { Image } from 'expo-image';
import { LinearGradient } from 'expo-linear-gradient';
import { StyleSheet, View, Text } from 'react-native';
export default function PressableFeedbackExample() {
return (
<PressableFeedback className="w-full aspect-square overflow-auto">
<Card className="flex-1">
<Image
source={{
uri: 'https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/neo2.jpeg',
}}
style={StyleSheet.absoluteFill}
contentFit="cover"
/>
<LinearGradient
colors={['rgba(0,0,0,0.1)', 'rgba(0,0,0,0.4)']}
style={StyleSheet.absoluteFill}
/>
<PressableFeedback.Ripple
animation={{
backgroundColor: { value: 'white' },
opacity: { value: [0, 0.3, 0] },
}}
/>
<View className="flex-1 gap-4" pointerEvents="box-none">
<Card.Body className="flex-1" pointerEvents="none">
<Card.Title className="text-base text-zinc-50 uppercase mb-0.5">
Neo
</Card.Title>
<Card.Description className="text-zinc-50 font-medium text-base">
家用机器人
</Card.Description>
</Card.Body>
<Card.Footer className="gap-3">
<View className="flex-row items-center justify-between">
<View pointerEvents="none">
<Text className="text-base text-white">即将开售</Text>
<Text className="text-base text-zinc-300">订阅通知</Text>
</View>
<Button size="sm" className="bg-white">
<Button.Label className="text-black">通知我</Button.Label>
</Button>
</View>
</Card.Footer>
</View>
</Card>
</PressableFeedback>
);
}
```
更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/pressable-feedback.tsx>)。
## API 参考
### PressableFeedback
| prop | type | default | description |
| ----------------------- | -------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 需要包裹按压反馈的内容 |
| `isDisabled` | `boolean` | `false` | 是否禁用 |
| `className` | `string` | - | 额外的 class |
| `animation` | `PressableFeedbackRootAnimation` | - | 通过 `{ scale: ... }` 自定义缩放；`false` 关闭根级缩放；`'disable-all'` 级联禁用全部 |
| `isAnimatedStyleActive` | `boolean` | `true` | 根内置动画样式是否启用 |
| `asChild` | `boolean` | `false` | 是否以子元素方式渲染 |
| `...rest` | `AnimatedProps<PressableProps>` | - | 支持 Reanimated `Animated` `Pressable` 的属性 |
#### PressableFeedbackRootAnimation
根 `animation` 遵循标准 `AnimationRoot` 控制流：
- `true` 或 `undefined`：使用默认内置缩放
- `false` 或 `"disabled"`：关闭根内置缩放（改用 `PressableFeedback.Scale` 时）
- `"disable-all"`：级联禁用全部动画（含内置缩放与子级 Scale、Highlight、Ripple）
- `object`：自定义内置缩放
| prop | type | default | description |
| ------- | ---------------------------------------- | ------- | ------------------------------------------------------------------------------- |
| `scale` | `PressableFeedbackScaleAnimation` | - | 自定义内置缩放（value、timingConfig 等） |
| `state` | `'disabled' \| 'disable-all' \| boolean` | - | 在保留配置的同时控制动画状态（例如运行时开关） |
### PressableFeedback.Scale
对容器内指定子元素应用缩放时使用；根上设 `animation={false}` 以关闭其内置缩放。
| prop | type | default | description |
| ----------------------- | --------------------------------- | ------- | ------------------------------------------------------------ |
| `className` | `string` | - | 额外的 class |
| `animation` | `PressableFeedbackScaleAnimation` | - | 缩放动画配置 |
| `isAnimatedStyleActive` | `boolean` | `true` | 是否启用 Reanimated 动画样式 |
| `style` | `ViewStyle` | - | 额外样式 |
| `...AnimatedProps` | `AnimatedProps<ViewProps>` | - | 支持 Reanimated `Animated.View` 的属性 |
#### PressableFeedbackScaleAnimation
缩放动画配置，可为：
- `false` 或 `"disabled"`：禁用缩放动画
- `true` 或 `undefined`：使用默认缩放动画
- `object`：自定义缩放配置
| prop | type | default | description |
| ------------------------ | ----------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------- |
| `state` | `'disabled' \| boolean` | - | 在自定义属性时禁用动画 |
| `value` | `number` | `0.985` | 按下时的缩放值（会随容器宽度自动调整） |
| `timingConfig` | `WithTimingConfig` | `{ duration: 300, easing: Easing.out(Easing.ease) }` | 时间曲线配置 |
| `ignoreScaleCoefficient` | `boolean` | `false` | 为 true 时忽略自动缩放系数，直接使用 `value` |
### PressableFeedback.Highlight
| prop | type | default | description |
| ----------------------- | ------------------------------------- | ------- | ------------------------------------------------------------ |
| `className` | `string` | - | 额外的 class |
| `animation` | `PressableFeedbackHighlightAnimation` | - | 高亮层动画配置 |
| `isAnimatedStyleActive` | `boolean` | `true` | 是否启用 Reanimated 动画样式 |
| `style` | `ViewStyle` | - | 额外样式 |
| `...AnimatedProps` | `AnimatedProps<ViewProps>` | - | 支持 Reanimated `Animated.View` 的属性 |
#### PressableFeedbackHighlightAnimation
高亮层动画配置，可为：
- `false` 或 `"disabled"`：禁用高亮动画
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| ----------------------- | ----------------------- | ------------------- | --------------------------------- |
| `state` | `'disabled' \| boolean` | - | 在自定义属性时禁用动画 |
| `opacity.value` | `[number, number]` | `[0, 0.1]` | 不透明度 [未按下, 按下] |
| `opacity.timingConfig` | `WithTimingConfig` | `{ duration: 200 }` | 时间曲线配置 |
| `backgroundColor.value` | `string` | 随主题灰色 | 高亮层背景色 |
### PressableFeedback.Ripple
| prop | type | default | description |
| ----------------------- | ----------------------------------------- | ------- | ------------------------------------------------------------ |
| `className` | `string` | - | 容器插槽的 class |
| `classNames` | `ElementSlots<RippleSlots>` | - | 各插槽 class（container、ripple） |
| `styles` | `Partial<Record<RippleSlots, ViewStyle>>` | - | 涟漪遮罩各部分的样式 |
| `animation` | `PressableFeedbackRippleAnimation` | - | 涟漪动画配置 |
| `isAnimatedStyleActive` | `boolean` | `true` | 是否启用 Reanimated 动画样式 |
| `...ViewProps` | `Omit<ViewProps, 'style'>` | - | 支持 `View` 属性（不含 `style`） |
#### `styles`
| prop | type | description |
| ----------- | ----------- | ------------- |
| `container` | `ViewStyle` | 容器插槽样式 |
| `ripple` | `ViewStyle` | 涟漪插槽样式 |
#### PressableFeedbackRippleAnimation
涟漪动画配置，可为：
- `false` 或 `"disabled"`：禁用涟漪动画
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| ------------------------------------ | -------------------------- | ----------------------- | ---------------------------------------------------------------------------- |
| `state` | `'disabled' \| boolean` | - | 在自定义属性时禁用动画 |
| `backgroundColor.value` | `string` | 随主题计算 | 涟漪背景色 |
| `progress.baseDuration` | `number` | `1000` | 涟漪进度基准时长（会按对角线自动调整） |
| `progress.minBaseDuration` | `number` | `750` | 进度动画最小时长 |
| `progress.ignoreDurationCoefficient` | `boolean` | `false` | 为 true 时忽略自动时长系数，直接使用基准时长 |
| `opacity.value` | `[number, number, number]` | `[0, 0.1, 0]` | 不透明度 [起始, 峰值, 结束] |
| `opacity.timingConfig` | `WithTimingConfig` | `{ duration: 200 }` | 时间曲线配置 |
| `scale.value` | `[number, number, number]` | `[0, 1, 1]` | 缩放 [起始, 峰值, 结束] |
| `scale.timingConfig` | `WithTimingConfig` | `{ duration: 200 }` | 时间曲线配置 |
#### `ElementSlots<RippleSlots>`
涟漪各插槽的额外 class：
| slot | description |
| ----------- | ------------------------------------------------------------------------------------------------------------------- |
| `container` | 外层容器（`absolute inset-0`），可通过 class 完全定制样式 |
| `ripple` | 内层涟漪（`absolute top-0 left-0 rounded-full`），带动画属性，不宜用 className 覆盖动画相关表现 |
apps/docs/content/docs/cn/native/components/(utilities)/scroll-shadow.mdx
+216
View File
@@ -0,0 +1,216 @@
---
title: ScrollShadow 滚动阴影
description: 根据滚动位置与溢出情况，为可滚动内容添加动态渐变边缘阴影。
links:
source_native: scroll-shadow/scroll-shadow.tsx
styles_native: scroll-shadow/scroll-shadow.styles.ts
---
<NativeVideoPlayerView
target="auto"
srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/scroll-shadow-docs-light.mp4"
srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/scoll-shadow-docs-dark.mp4.mp4"
/>
## 导入
```tsx
import { ScrollShadow } from 'heroui-native';
```
## 结构
```tsx
<ScrollShadow LinearGradientComponent={LinearGradient}>
<ScrollView>...</ScrollView>
</ScrollShadow>
```
- **ScrollShadow**：包裹可滚动组件，按滚动位置与内容溢出在边缘显示动态渐变阴影；自动识别横向/纵向滚动并管理阴影显隐。
- **LinearGradientComponent**：必填，传入兼容库的 `LinearGradient`（如 expo-linear-gradient、react-native-linear-gradient）以绘制渐变阴影。
## 用法
### 基础用法
包裹任意可滚动组件，自动在边缘添加阴影。
```tsx
<ScrollShadow LinearGradientComponent={LinearGradient}>
<ScrollView>...</ScrollView>
</ScrollShadow>
```
### 横向滚动
根据子组件的 `horizontal` 属性自动识别横向滚动。
```tsx
<ScrollShadow LinearGradientComponent={LinearGradient}>
<FlatList horizontal data={data} renderItem={...} />
</ScrollShadow>
```
### 自定义阴影尺寸
用 `size` 控制渐变阴影的高度或宽度（像素）。
```tsx
<ScrollShadow size={100} LinearGradientComponent={LinearGradient}>
<ScrollView>...</ScrollView>
</ScrollShadow>
```
### 显隐控制
用 `visibility` 指定显示哪些边的阴影。
```tsx
<ScrollShadow visibility="top" LinearGradientComponent={LinearGradient}>
<ScrollView>...</ScrollView>
</ScrollShadow>
<ScrollShadow visibility="bottom" LinearGradientComponent={LinearGradient}>
<ScrollView>...</ScrollView>
</ScrollShadow>
<ScrollShadow visibility="none" LinearGradientComponent={LinearGradient}>
<ScrollView>...</ScrollView>
</ScrollShadow>
```
### 自定义阴影颜色
覆盖默认使用主题背景的阴影颜色。
```tsx
<ScrollShadow color="#ffffff" LinearGradientComponent={LinearGradient}>
<ScrollView>...</ScrollView>
</ScrollShadow>
```
### 自定义滚动处理
**重要：** ScrollShadow 内部会将子节点转为 Reanimated 动画组件。若需使用 `onScroll`，必须使用 `react-native-reanimated` 的 `useAnimatedScrollHandler`，而不能使用普通的 `onScroll`。
```tsx
import { LinearGradient } from 'expo-linear-gradient';
import Animated, { useAnimatedScrollHandler } from 'react-native-reanimated';
const scrollHandler = useAnimatedScrollHandler({
onScroll: (event) => {
console.log(event.contentOffset.y);
},
});
<ScrollShadow LinearGradientComponent={LinearGradient}>
<Animated.ScrollView onScroll={scrollHandler}>...</Animated.ScrollView>
</ScrollShadow>;
```
## 示例
```tsx
import { ScrollShadow, Surface } from 'heroui-native';
import { LinearGradient } from 'expo-linear-gradient';
import { FlatList, ScrollView, Text, View } from 'react-native';
export default function ScrollShadowExample() {
const horizontalData = Array.from({ length: 10 }, (_, i) => ({
id: i,
title: `Card ${i + 1}`,
}));
return (
<View className="flex-1 bg-background">
<Text className="px-5 py-3 text-lg font-semibold">Horizontal List</Text>
<ScrollShadow LinearGradientComponent={LinearGradient}>
<FlatList
data={horizontalData}
horizontal
renderItem={({ item }) => (
<Surface variant="2" className="w-32 h-24 justify-center px-4">
<Text>{item.title}</Text>
</Surface>
)}
showsHorizontalScrollIndicator={false}
contentContainerClassName="p-5 gap-4"
/>
</ScrollShadow>
<Text className="px-5 py-3 text-lg font-semibold">Vertical Content</Text>
<ScrollShadow
size={80}
className="h-48"
LinearGradientComponent={LinearGradient}
>
<ScrollView
contentContainerClassName="p-5"
showsVerticalScrollIndicator={false}
>
<Text className="mb-4 text-2xl font-bold">Long Content</Text>
<Text className="mb-4 text-base leading-6">
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
ad minim veniam, quis nostrud exercitation ullamco laboris.
</Text>
<Text className="mb-4 text-base leading-6">
Sed ut perspiciatis unde omnis iste natus error sit voluptatem
accusantium doloremque laudantium, totam rem aperiam, eaque ipsa
quae ab illo inventore veritatis et quasi architecto beatae vitae.
</Text>
</ScrollView>
</ScrollShadow>
</View>
);
}
```
更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/scroll-shadow.tsx)。
## API 参考
### ScrollShadow
| prop | type | default | description |
| ------------------------- | ---------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------- |
| `children` | `React.ReactElement` | - | 需要增强阴影的可滚动组件，须为单一 React 元素（ScrollView、FlatList 等） |
| `LinearGradientComponent` | `ComponentType<`<br/>`LinearGradientProps>` | **必填** | 来自任意兼容库的 LinearGradient 组件 |
| `size` | `number` | `50` | 渐变阴影高度或宽度（像素） |
| `orientation` | `'horizontal' \| 'vertical'` | 自动检测 | 阴影方向；未提供时根据子组件 `horizontal` 自动检测 |
| `visibility` | `'auto' \| 'top' \| 'bottom' \| 'left' \| 'right' \| 'both' \| 'none'` | `'auto'` | 阴影显隐模式；`auto` 根据滚动位置与溢出自动显示 |
| `color` | `string` | 主题色 | 渐变阴影自定义颜色；未提供时使用主题背景色 |
| `isEnabled` | `boolean` | `true` | 是否启用阴影效果 |
| `animation` | `ScrollShadowRootAnimation` | - | 动画配置 |
| `className` | `string` | - | 容器额外 class |
| `...ViewProps` | `ViewProps` | - | 支持 React Native `View` 的全部标准属性 |
#### ScrollShadowRootAnimation
ScrollShadow 动画配置，可为：
- `false` 或 `"disabled"`：仅关闭根动画
- `"disable-all"`：关闭所有动画（含子级）
- `true` 或 `undefined`：使用默认动画
- `object`：自定义动画配置
| prop | type | default | description |
| --------------- | ---------------------------------------- | -------- | ----------------------------------------------------------------------------------- |
| `state` | `'disabled' \| 'disable-all' \| boolean` | - | 关闭动画的同时仍允许自定义属性 |
| `opacity.value` | `[number, number]` | `[0, 1]` | 不透明度 [初始, 激活]；底部/右侧阴影时顺序相反 |
### LinearGradientProps
`LinearGradientComponent` 应接受以下属性：
| prop | type | description |
| ----------- | --------------------------------- | ------------------------------------------------------------------ |
| `colors` | `any` | 渐变颜色数组 |
| `locations` | `any`（可选） | 各颜色停靠位置 |
| `start` | `any`（可选） | 渐变起点，如 `{ x: 0, y: 0 }` |
| `end` | `any`（可选） | 渐变终点，如 `{ x: 1, y: 0 }` |
| `style` | `StyleProp<ViewStyle>`（可选） | 应用于渐变视图的样式 |
## 特别说明
**重要：** ScrollShadow 内部会将子节点转为 Reanimated 动画组件。若需在可滚动组件上使用滚动回调，必须使用 `react-native-reanimated` 的 `useAnimatedScrollHandler`，不能使用标准 `onScroll`。
apps/docs/content/docs/cn/native/components/index.mdx
+48
View File
@@ -0,0 +1,48 @@
---
title: 所有组件
description: 浏览 HeroUI Native 提供的全部组件；更多组件将陆续推出。
---
## 按钮
<NativeComponentsCategory category="Buttons" />
## 集合
<NativeComponentsCategory category="Collections" />
## 控件
<NativeComponentsCategory category="Controls" />
## 表单
<NativeComponentsCategory category="Forms" />
## 导航
<NativeComponentsCategory category="Navigation" />
## 浮层
<NativeComponentsCategory category="Overlays" />
## 反馈
<NativeComponentsCategory category="Feedback" />
## 布局
<NativeComponentsCategory category="Layout" />
## 媒体
<NativeComponentsCategory category="Media" />
## 数据展示
<NativeComponentsCategory category="Data Display" />
## 工具
<NativeComponentsCategory category="Utilities" />
apps/docs/content/docs/cn/native/components/meta.json
+49
View File
@@ -0,0 +1,49 @@
{
"title": "组件",
"description": "HeroUI Native 组件",
"root": true,
"icon": "circles-4-diamond",
"pages": [
"index",
"---组件---",
"(navigation)/accordion",
"(feedback)/alert",
"(media)/avatar",
"(overlays)/bottom-sheet",
"(buttons)/button",
"(layout)/card",
"(forms)/checkbox",
"(data-display)/chip",
"(buttons)/close-button",
"(forms)/control-field",
"(forms)/description",
"(overlays)/dialog",
"(forms)/field-error",
"(forms)/input",
"(forms)/input-group",
"(forms)/input-otp",
"(forms)/label",
"(buttons)/link-button",
"(navigation)/list-group",
"(collections)/menu",
"(overlays)/popover",
"(utilities)/pressable-feedback",
"(forms)/radio-group",
"(utilities)/scroll-shadow",
"(controls)/slider",
"(forms)/search-field",
"(forms)/select",
"(layout)/separator",
"(feedback)/skeleton",
"(feedback)/skeleton-group",
"(feedback)/spinner",
"(layout)/surface",
"(controls)/switch",
"(navigation)/tabs",
"(collections)/tag-group",
"(typography)/text",
"(forms)/text-area",
"(forms)/text-field",
"(overlays)/toast"
]
}
apps/docs/content/docs/cn/native/getting-started/(handbook)/animation.mdx
+207
View File
@@ -0,0 +1,207 @@
---
title: 动画
description: 为 HeroUI Native 组件添加流畅动画与过渡
icon: copy-transparent
---
HeroUI Native 的动画基于 [react-native-reanimated](https://docs.swmansion.com/react-native-reanimated/)，手势由 [react-native-gesture-handler](https://docs.swmansion.com/react-native-gesture-handler/) 处理。若需更细粒度控制，建议先熟悉二者。
## `animation` 属性
每个带动画的组件都暴露统一的 `animation` 属性，用于控制该组件上的全部动画：可调整数值、时间配置、布局动画，或完全关闭动画。
**做法：** 处理动画时，先查看目标组件是否提供 `animation` 属性。
## 修改动画
向 `animation` 传入对象即可定制。不同组件暴露的可调属性不同。若只想微调内置动画，可使用我们提供的各项配置；若要完全自定义动画逻辑，通常需要自行编写带动画的自定义组件。
### 示例 1：简单数值调整
调整缩放、透明度或颜色等数值：
```tsx
import {Switch} from 'heroui-native';
<Switch
animation={{
scale: {
value: [1, 0.9], // [unpressed, pressed]
},
backgroundColor: {
value: ['#172554', '#eab308'], // [unselected, selected]
},
}}>
<Switch.Thumb />
</Switch>;
```
### 示例 2：时间曲线配置
自定义时长与缓动：
```tsx
import {Accordion} from 'heroui-native';
<Accordion>
<Accordion.Item value="1">
<Accordion.Trigger>
<Accordion.Indicator
animation={{
rotation: {
value: [0, -180],
springConfig: {
damping: 60,
stiffness: 900,
mass: 3,
},
},
}}
/>
</Accordion.Trigger>
</Accordion.Item>
</Accordion>;
```
### 示例 3：布局动画（进入 / 退出）
使用 Reanimated 的布局动画 API：
```tsx
import {Accordion} from 'heroui-native';
import {FadeInRight, FadeInLeft, ZoomIn} from 'react-native-reanimated';
import {Easing} from 'react-native-reanimated';
<Accordion>
<Accordion.Item value="1">
<Accordion.Content
animation={{
entering: {
value: FadeInRight.delay(50).easing(Easing.inOut(Easing.ease)),
},
}}>
Content here
</Accordion.Content>
</Accordion.Item>
</Accordion>;
```
### 示例 4：使用 `state` 精细控制
`state` 可在关闭动画的同时仍保留属性配置，便于微调而不真正播放动画：
```tsx
import {Switch} from 'heroui-native';
<Switch
animation={{
state: 'disabled', // Disable animations but allow property customization
scale: {
value: 0.95, // This value is still respected even though animations are disabled
},
backgroundColor: {
value: ['#172554', '#eab308'],
},
}}>
<Switch.Thumb />
</Switch>
```
`state` 可取：
- `'disabled'`：关闭动画，但仍可配置属性值
- `'disable-all'`：关闭自身及子级全部动画（仅在根级可用）
- `boolean`：简单开关（`true` 启用，`false` 禁用）
这样既能精细控制动画行为，又能在不启用动画的情况下自定义属性值。
## 关闭动画
可通过 `animation` 在不同层级关闭动画。
### 关闭选项
- `animation={false}` 或 `animation="disabled"`：仅关闭当前组件动画
- `animation="disable-all"`：关闭根级及其子级全部动画（仅根级可用）
- `animation={true}` 或 `animation={undefined}`：使用默认动画
### 组件级关闭
仅关闭某个子部件的动画：
```tsx
<Switch>
<Switch.Thumb animation={false} />
</Switch>
```
### 根级 `disable-all`
`"disable-all"` 仅在复合组件根级可用，会向下级联，**包括**树中的独立组件（如 `Button`、`Spinner` 等），不仅限于复合子部件：
```tsx
// Disables all animations including Button components inside Card
<Card animation="disable-all">
<Card.Body>
<Card.Title>$450</Card.Title>
<Card.Description>Living room Sofa</Card.Description>
</Card.Body>
<Card.Footer className="gap-3">
<Button variant="primary">Buy now</Button>
<Button variant="ghost">Add to cart</Button>
</Card.Footer>
</Card>
```
**注意：** `"disable-all"` 会级联到所有子组件，包括独立的 `Button`、`Spinner` 等。
## 全局动画配置
在 `HeroUINativeProvider` 上统一关闭应用内全部 HeroUI Native 动画：
```tsx
import {HeroUINativeProvider} from 'heroui-native';
<HeroUINativeProvider
config={{
animation: 'disable-all',
}}>
<App />
</HeroUINativeProvider>;
```
这会覆盖各组件自身的 `animation` 设置，全局禁用动画。
## 无障碍
系统「减少动态效果」会在底层自动处理：当用户开启该无障碍选项时，库会通过 `GlobalAnimationSettingsProvider` 与 Reanimated 的 `useReducedMotion()` 全局关闭动画。
你通常无需额外编码，库会尊重系统无障碍偏好。
## 动画状态管理
内部会统一管理禁用态，避免关闭动画后出现卡顿或跳变：禁用时组件会直接落到终态，而不是播放到一半。
## 子级渲染函数
许多组件支持将 `children` 设为函数，便于根据 `isSelected` 等状态渲染：
```tsx
import {Switch} from 'heroui-native';
<Switch
isSelected={isSelected}
onSelectedChange={setIsSelected}>
{({isSelected, isDisabled}) => (
<Switch.Thumb>{isSelected ? <CheckIcon /> : <XIcon />}</Switch.Thumb>
)}
</Switch>;
```
该模式便于根据选中、禁用等状态构建动态界面。
## 下一步
- [样式](/docs/native/getting-started/styling)
- [主题](/docs/native/getting-started/theming)
- [颜色](/docs/native/getting-started/colors)
apps/docs/content/docs/cn/native/getting-started/(handbook)/colors.mdx
+478
View File
@@ -0,0 +1,478 @@
---
title: 颜色
description: HeroUI Native 的调色板与主题系统
icon: bucket-paint
links:
themes: true
tailwind: theme
---
import {ColorSectionSideBySide, ColorSectionStacked, ColorSectionFormField, ColorSectionPrimitive} from "@/components/color-section";
HeroUI Native 的颜色体系围绕语义意图构建，而非堆砌视觉色板。系统不会暴露庞大的原始色表，而是定义一小套有意义的色彩角色，覆盖绝大多数界面需求。
系统中的多数颜色会由少量基础值自动派生。这样 HeroUI 能在保持对比度、层级与主题行为一致的同时，让整套体系易于理解与修改。
颜色应首先传达用途与状态；视觉变化来自尺度、强调与上下文。
## 强调色
强调色代表品牌或产品的主识别色，用于吸引对关键操作、高亮与重点时刻的注意。
强调色应有意识地节制使用。滥用会削弱其冲击力，并破坏视觉层级。多数情况下，组件会从基础强调色自动派生悬停、柔和背景与聚焦等相关取值。
<ColorSectionSideBySide
name="强调色"
baseVariable="--accent"
hoverVariable="--accent"
hoverCssValue="color-mix(in oklab, var(--accent) 90%, var(--accent-foreground) 10%)"
foregroundVariable="--accent-foreground"
soft={{
baseVariable: "--accent",
baseCssValue: "color-mix(in oklab, var(--accent) 15%, transparent)",
hoverVariable: "--accent",
hoverCssValue: "color-mix(in oklab, var(--accent) 20%, transparent)",
foregroundVariable: "--accent",
foregroundCssValue: "var(--accent)",
}}
/>
## 默认（中性色）
默认色构成系统的中性骨架，用于大多数非强调的界面元素。
<ColorSectionSideBySide
name="默认"
baseVariable="--default"
hoverVariable="--default"
hoverCssValue="color-mix(in oklab, var(--default) 96%, var(--default-foreground) 4%)"
foregroundVariable="--default-foreground"
/>
## 成功
成功色传达积极结果、确认与完成状态，常见于反馈组件、状态指示与校验通过等场景。
<ColorSectionSideBySide
name="成功"
baseVariable="--success"
hoverVariable="--success"
hoverCssValue="color-mix(in oklab, var(--success) 90%, var(--success-foreground) 10%)"
foregroundVariable="--success-foreground"
soft={{
baseVariable: "--success",
baseCssValue: "color-mix(in oklab, var(--success) 15%, transparent)",
hoverVariable: "--success",
hoverCssValue: "color-mix(in oklab, var(--success) 20%, transparent)",
foregroundVariable: "--success",
foregroundCssValue: "var(--success)",
}}
/>
## 警告
警告色表示需谨慎、存在风险，或需要留意但非破坏性的操作，常用于提示、消息以及用户应暂停或复核信息的过渡状态。
<ColorSectionSideBySide
name="警告"
baseVariable="--warning"
hoverVariable="--warning"
hoverCssValue="color-mix(in oklab, var(--warning) 90%, var(--warning-foreground) 10%)"
foregroundVariable="--warning-foreground"
soft={{
baseVariable: "--warning",
baseCssValue: "color-mix(in oklab, var(--warning) 15%, transparent)",
hoverVariable: "--warning",
hoverCssValue: "color-mix(in oklab, var(--warning) 20%, transparent)",
foregroundVariable: "--warning",
foregroundCssValue: "var(--warning)",
}}
/>
## 危险
危险色表示破坏性、不可逆或关键的操作与状态，应一眼可辨，并稳定用于错误、危险按钮与严重告警。
<ColorSectionSideBySide
name="危险"
baseVariable="--danger"
hoverVariable="--danger"
hoverCssValue="color-mix(in oklab, var(--danger) 90%, var(--danger-foreground) 10%)"
foregroundVariable="--danger-foreground"
soft={{
baseVariable: "--danger",
baseCssValue: "color-mix(in oklab, var(--danger) 15%, transparent)",
hoverVariable: "--danger",
hoverCssValue: "color-mix(in oklab, var(--danger) 20%, transparent)",
foregroundVariable: "--danger",
foregroundCssValue: "var(--danger)",
}}
/>
## 前景色
前景色用于正文级内容，如文字与图标。这些颜色针对可读性与无障碍优化，并会随背景与表面上下文自动适配。请勿在组件内硬编码前景色。
<ColorSectionStacked
lightColors={[
{ label: "前景", variable: "--foreground" },
{ label: "弱化", variable: "--muted" },
{ label: "分段", variable: "--segment" },
{ label: "覆盖层", variable: "--overlay" },
{ label: "链接", variable: "--link" },
]}
darkColors={[
{ label: "前景", variable: "--foreground", border: true },
{ label: "弱化", variable: "--muted", border: true },
{ label: "分段", variable: "--segment", border: true },
{ label: "覆盖层", variable: "--overlay", border: true },
{ label: "链接", variable: "--link", border: true },
]}
/>
## 背景色
背景色定义界面的基底画布，在保持视觉克制的前提下建立整体对比与氛围。
<ColorSectionStacked
lightColors={[
{ label: "背景", variable: "--background", border: true },
{ label: "次级", variable: "--background", cssValue: "color-mix(in oklab, var(--background) 96%, var(--foreground) 4%)", border: true },
{ label: "第三级", variable: "--background", cssValue: "color-mix(in oklab, var(--background) 92%, var(--foreground) 8%)", border: true },
{ label: "反色", variable: "--foreground" },
]}
darkColors={[
{ label: "背景", variable: "--background", border: true },
{ label: "次级", variable: "--background", cssValue: "color-mix(in oklab, var(--background) 96%, var(--foreground) 4%)", border: true },
{ label: "第三级", variable: "--background", cssValue: "color-mix(in oklab, var(--background) 92%, var(--foreground) 8%)", border: true },
{ label: "反色", variable: "--foreground", border: true },
]}
/>
## 表面色
表面色叠在背景之上，用于卡片、面板、模态与下拉等容器。表面通过抬升、对比与分层形成区隔与层级，而非依赖强烈的色相跳跃。
<ColorSectionStacked
lightColors={[
{ label: "表面", variable: "--surface", border: true },
{ label: "次级", variable: "--surface-secondary", border: true },
{ label: "第三级", variable: "--surface-tertiary", border: true },
]}
darkColors={[
{ label: "表面", variable: "--surface", border: true },
{ label: "次级", variable: "--surface-secondary", border: true },
{ label: "第三级", variable: "--surface-tertiary", border: true },
]}
/>
## 表单字段
表单字段色是面向输入、控件与可交互字段的专用令牌，覆盖默认、聚焦与悬停等多种状态。将其独立出来，可让表单元素在视觉上与按钮及界面其余部分保持清晰区分。
<ColorSectionFormField
colors={{
bg: "--field-background",
bgHover: "color-mix(in oklab, var(--field-background) 90%, var(--field-foreground) 10%)",
placeholder: "--field-placeholder",
foreground: "--field-foreground",
}}
/>
## 分隔线
分隔线色用于分割线、描边与轻量边界，用来组织内容、引导视线而不增加噪点。分隔线色应保持低对比、不抢眼。
<ColorSectionStacked
lightColors={[
{ label: "分隔线", variable: "--separator", border: true },
{ label: "次级", variable: "--surface", cssValue: "color-mix(in oklab, var(--surface) 85%, var(--surface-foreground) 15%)", border: true },
{ label: "第三级", variable: "--surface", cssValue: "color-mix(in oklab, var(--surface) 81%, var(--surface-foreground) 19%)", border: true },
]}
darkColors={[
{ label: "分隔线", variable: "--separator", border: true },
{ label: "次级", variable: "--surface", cssValue: "color-mix(in oklab, var(--surface) 85%, var(--surface-foreground) 15%)", border: true },
{ label: "第三级", variable: "--surface", cssValue: "color-mix(in oklab, var(--surface) 81%, var(--surface-foreground) 19%)", border: true },
]}
/>
## 其他
其他颜色在界面中承担特定工具性角色，用于组织内容、引导视线而不增加噪点。
<ColorSectionStacked
lightColors={[
{ label: "边框", variable: "--border" },
{ label: "背衬", variable: "--backdrop" },
{ label: "覆盖层", variable: "--overlay", border: true },
{ label: "分段", variable: "--segment", border: true },
]}
darkColors={[
{ label: "边框", variable: "--border" },
{ label: "背衬", variable: "--backdrop" },
{ label: "覆盖层", variable: "--overlay", border: true },
{ label: "分段", variable: "--segment", border: true },
]}
/>
## 基础色
基础色是与模式无关的底层取值，作为语义色令牌的根基，在明暗主题之间不会改变。
<ColorSectionPrimitive
colors={[
{ label: "白", variable: "--white", border: true, tooltip: "--white: oklch(100% 0 0)" },
{ label: "黑", variable: "--black", tooltip: "--black: oklch(0% 0 0)" },
{ label: "雪白", variable: "--snow", border: true, tooltip: "--snow: oklch(0.9911 0 0)" },
{ label: "月蚀", variable: "--eclipse", tooltip: "--eclipse: oklch(0.2103 0.0059 285.89)" },
]}
/>
## 如何使用颜色
**在组件中：**
```tsx
import { View, Text } from 'react-native';
<View className="bg-background flex-1 p-4">
<Text className="text-foreground mb-4">内容</Text>
<Button variant="primary" className="bg-accent">
<Button.Label className="text-accent-foreground">点击我</Button.Label>
</Button>
</View>;
```
**在 CSS 文件中：**
```css title="global.css"
/* 直接使用 CSS 变量 */
.container {
flex: 1;
background-color: var(--accent);
width: 50px;
height: 50px;
border-radius: var(--radius);
}
```
## 默认主题
完整主题定义见仓库中的 [variables.css](https://github.com/heroui-inc/heroui-native/blob/main/src/styles/variables.css)。该主题通过 [Uniwind 主题系统](https://docs.uniwind.dev/theming/basics) 在明暗模式间自动切换，并支持跟随系统与在代码中切换主题。
<CollapsibleCode lang="css" code={` @theme {
/* 基础色（在明暗模式间保持不变） */
--white: oklch(100% 0 0);
--black: oklch(0% 0 0);
--snow: oklch(0.9911 0 0);
--eclipse: oklch(0.2103 0.0059 285.89);
/* 边框 */
--border-width: 1px;
--field-border-width: 0px;
/* 基础圆角 */
--radius: 0.5rem;
--field-radius: calc(var(--radius) * 1.5);
/* 不透明度 */
--opacity-disabled: 0.5;
}
@layer theme {
:root {
@variant light {
/* 基础颜色 */
--background: oklch(0.9702 0 0);
--foreground: var(--eclipse);
/* 表面 */
--surface: var(--white);
--surface-foreground: var(--foreground);
--surface-secondary: oklch(0.9524 0.0013 286.37);
--surface-secondary-foreground: var(--foreground);
--surface-tertiary: oklch(0.9373 0.0013 286.37);
--surface-tertiary-foreground: var(--foreground);
/* 覆盖层 */
--overlay: var(--white);
--overlay-foreground: var(--foreground);
--backdrop: oklch(0% 0 0 / 20%);
--muted: oklch(0.5517 0.0138 285.94);
--default: oklch(94% 0.001 286.375);
--default-foreground: var(--eclipse);
--accent: oklch(0.6204 0.195 253.83);
--accent-foreground: var(--snow);
/* 表单字段 */
--field-background: var(--white);
--field-foreground: oklch(0.2103 0.0059 285.89);
--field-placeholder: var(--muted);
--field-border: transparent;
/* 状态色 */
--success: oklch(0.7329 0.1935 150.81);
--success-foreground: var(--eclipse);
--warning: oklch(0.7819 0.1585 72.33);
--warning-foreground: var(--eclipse);
--danger: oklch(0.6532 0.2328 25.74);
--danger-foreground: var(--snow);
/* 组件颜色 */
--segment: var(--white);
--segment-foreground: var(--eclipse);
/* 杂项颜色 */
--border: oklch(90% 0.004 286.32);
--separator: oklch(74% 0.004 286.32);
--focus: var(--accent);
--link: var(--foreground);
}
@variant dark {
/* 基础颜色 */
--background: oklch(12% 0.005 285.823);
--foreground: var(--snow);
/* 表面 */
--surface: oklch(0.2103 0.0059 285.89);
--surface-foreground: var(--foreground);
--surface-secondary: oklch(0.257 0.0037 286.14);
--surface-secondary-foreground: var(--foreground);
--surface-tertiary: oklch(0.2721 0.0024 247.91);
--surface-tertiary-foreground: var(--foreground);
/* 覆盖层 */
--overlay: oklch(0.2103 0.0059 285.89);
--overlay-foreground: var(--foreground);
--backdrop: oklch(0% 0 0 / 20%);
--muted: oklch(70.5% 0.015 286.067);
--default: oklch(27.4% 0.006 286.033);
--default-foreground: var(--snow);
--accent: oklch(0.6204 0.195 253.83);
--accent-foreground: var(--snow);
/* 表单字段 */
--field-background: oklch(0.2103 0.0059 285.89);
--field-foreground: var(--foreground);
--field-placeholder: var(--muted);
--field-border: transparent;
/* 状态色 */
--success: oklch(0.7329 0.1935 150.81);
--success-foreground: var(--eclipse);
--warning: oklch(0.8203 0.1388 76.34);
--warning-foreground: var(--eclipse);
--danger: oklch(0.594 0.1967 24.63);
--danger-foreground: var(--snow);
/* 组件颜色 */
--segment: oklch(0.3964 0.01 285.93);
--segment-foreground: var(--foreground);
/* 杂项颜色 */
--border: oklch(28% 0.006 286.033);
--separator: oklch(40% 0.006 286.033);
--focus: var(--accent);
--link: var(--foreground);
}
}
}
`}
/>
## 自定义颜色
**覆盖已有颜色：**
```css
@layer theme {
@variant light {
/* 覆盖默认颜色 */
--accent: oklch(0.65 0.25 270); /* 自定义靛蓝强调色 */
--success: oklch(0.65 0.15 155);
}
@variant dark {
/* 覆盖深色主题颜色 */
--accent: oklch(0.65 0.25 270);
--success: oklch(0.75 0.12 155);
}
}
```
**提示：** 可在 [oklch.com](https://oklch.com) 转换颜色。
**添加自定义颜色：**
```css
@layer theme {
@variant light {
--info: oklch(0.6 0.15 210);
--info-foreground: oklch(0.98 0 0);
}
@variant dark {
--info: oklch(0.7 0.12 210);
--info-foreground: oklch(0.15 0 0);
}
}
@theme inline {
--color-info: var(--info);
--color-info-foreground: var(--info-foreground);
}
```
随后即可使用：
```tsx
import { View, Text } from 'react-native';
<View className="bg-info p-4 rounded-lg">
<Text className="text-info-foreground">提示信息</Text>
</View>;
```
> **注意：** 若要进一步了解主题变量及其在 Tailwind CSS v4 中的行为，请参阅 [Tailwind CSS 主题文档](https://tailwindcss.com/docs/theme)。
## useThemeColor 钩子
`useThemeColor` 钩子已增强，支持一次选取多种颜色，在复杂主题场景下更灵活。
**一次选取多种颜色：**
现在可以同时选取多种颜色，在需要一并处理相关色值时很有用：
```tsx
import { useThemeColor } from 'heroui-native';
// 一次选取多种颜色
const [accent, accentForeground, success, danger] = useThemeColor([
'accent',
'accentForeground',
'success',
'danger',
]);
// 使用所选颜色
<View style={{ backgroundColor: accent }}>
<Text style={{ color: accentForeground }}>强调色文字</Text>
</View>;
```
该改进在需要同时选取并应用多种颜色时，可提升性能，也便于管理复杂的主题组合。
apps/docs/content/docs/cn/native/getting-started/(handbook)/composition.mdx
+201
View File
@@ -0,0 +1,201 @@
---
title: 组合
description: 用组件组合模式搭建灵活 UI
icon: layers
---
HeroUI Native 通过组合模式实现灵活、可定制的组件：可更换实际渲染元素、将多个部件拼在一起，并完全掌控结构。
## 复合组件
HeroUI Native 采用点记法的复合组件——子组件作为属性导出（如 `Button.Label`、`Dialog.Trigger`、`Accordion.Item`），共同构成完整界面。
```tsx
import { Button, Dialog } from 'heroui-native';
function DialogExample() {
return (
<Dialog>
<Dialog.Trigger>
打开对话框
</Dialog.Trigger>
<Dialog.Portal>
<Dialog.Overlay />
<Dialog.Content>
<Dialog.Close />
<Dialog.Title>对话框标题</Dialog.Title>
<Dialog.Description>对话框说明</Dialog.Description>
</Dialog.Content>
</Dialog.Portal>
</Dialog>
);
}
```
## asChild 属性
`asChild` 用于改变组件实际渲染的元素。为 `true` 时，HeroUI Native 会克隆子元素并合并属性，而不是渲染默认包裹节点。
```tsx
import { Button, Dialog } from 'heroui-native';
function DialogExample() {
return (
<Dialog>
{/* asChild：Button 直接作为触发器，无额外包裹 */}
<Dialog.Trigger asChild>
<Button variant="primary">打开对话框</Button>
</Dialog.Trigger>
<Dialog.Portal>
<Dialog.Overlay />
<Dialog.Content>
{/* Dialog.Close 也可使用 asChild */}
<Dialog.Close asChild>
<Button variant="ghost" size="sm">取消</Button>
</Dialog.Close>
<Dialog.Title>对话框标题</Dialog.Title>
<Dialog.Description>对话框说明</Dialog.Description>
</Dialog.Content>
</Dialog.Portal>
</Dialog>
);
}
```
## 自定义组件
通过组合 HeroUI Native 原语封装自己的组件：
```tsx
import { Button, Card, Popover } from 'heroui-native';
import { View } from 'react-native';
// 商品卡片
function ProductCard({ title, description, price, onBuy, ...props }) {
return (
<Card {...props}>
<Card.Body>
<Card.Title>{price}</Card.Title>
<Card.Title>{title}</Card.Title>
<Card.Description>{description}</Card.Description>
</Card.Body>
<Card.Footer>
<Button variant="primary" onPress={onBuy}>
<Button.Label>立即购买</Button.Label>
</Button>
</Card.Footer>
</Card>
);
}
// 带 Popover 的按钮
function PopoverButton({ children, popoverContent, ...props }) {
return (
<Popover>
<Popover.Trigger asChild>
<Button {...props}>
<Button.Label>{children}</Button.Label>
</Button>
</Popover.Trigger>
<Popover.Portal>
<Popover.Overlay />
<Popover.Content>
<Popover.Close />
{popoverContent}
</Popover.Content>
</Popover.Portal>
</Popover>
);
}
// 用法
<ProductCard
title="客厅沙发"
description="适合现代家居空间"
price="$450"
onBuy={() => console.log('购买')}
/>
<PopoverButton variant="tertiary" popoverContent={
<View>
<Popover.Title>说明</Popover.Title>
<Popover.Description>更多详情见此处</Popover.Description>
</View>
}>
显示说明
</PopoverButton>
```
## 自定义变体
可用 `tailwind-variants` 扩展样式。**文字颜色类须加在 `Button.Label` 上，而不是父级 `Button`：**
```tsx
import { Button } from 'heroui-native';
import type { ButtonRootProps } from 'heroui-native';
import { tv, type VariantProps } from 'tailwind-variants';
const customButtonVariants = tv({
base: 'font-semibold rounded-lg',
variants: {
intent: {
primary: 'bg-blue-500',
secondary: 'bg-gray-200',
danger: 'bg-red-500',
},
},
defaultVariants: {
intent: 'primary',
},
});
const customLabelVariants = tv({
base: '',
variants: {
intent: {
primary: 'text-white',
secondary: 'text-gray-800',
danger: 'text-white',
},
},
defaultVariants: {
intent: 'primary',
},
});
type CustomButtonVariants = VariantProps<typeof customButtonVariants>;
interface CustomButtonProps
extends Omit<ButtonRootProps, 'className' | 'variant'>,
CustomButtonVariants {
className?: string;
labelClassName?: string;
}
export function CustomButton({
intent,
className,
labelClassName,
children,
...props
}: CustomButtonProps) {
return (
<Button
className={customButtonVariants({ intent, className })}
{...props}
>
<Button.Label
className={customLabelVariants({ intent, className: labelClassName })}
>
{children}
</Button.Label>
</Button>
);
}
```
## 下一步
- 了解 [样式](/docs/native/getting-started/styling) 体系
- 阅读 [主题](/docs/native/getting-started/theming) 文档
- 探索 [动画](/docs/native/getting-started/animation) 选项
apps/docs/content/docs/cn/native/getting-started/(handbook)/portal.mdx
+143
View File
@@ -0,0 +1,143 @@
---
title: Portal
icon: windows
---
Portal 可将子节点渲染到应用中的其他位置，特别适用于需要浮在其他内容之上的组件，例如模态框、覆盖层与弹出层。
## 默认配置
默认情况下，`PortalHost` 已包含在 `HeroUINativeProvider` 中，无需手动添加。Provider 会自动为所有使用 Portal 的组件设置好Portal系统。
## 进阶用法
如需自定义Portal实现，可直接从 `heroui-native` 导入 `Portal` 与 `PortalHost`：
```tsx
import { Portal, PortalHost } from "heroui-native";
import { View, Text } from "react-native";
function AppLayout() {
return (
<View className="flex-1">
<View className="p-5">
<Text>Header Content</Text>
</View>
<View className="flex-1 p-5">
<Text>Main Content Area</Text>
<CustomNotification />
</View>
{/* Portal host positioned at the top of the screen */}
<PortalHost name="notification-host" />
</View>
);
}
function CustomNotification() {
return (
<Portal name="notification-portal" hostName="notification-host">
<View className="absolute top-0 left-0 right-0 bg-blue-500 p-4">
<Text>This notification appears at the top via Portal</Text>
</View>
</Portal>
);
}
```
本例中，`CustomNotification` 组件通过 `Portal` 将内容渲染到位于屏幕顶部的 `PortalHost` 处，使通知浮于所有其他内容之上，无论它在组件树中的实际定义位置在哪。
## 状态管理注意事项
父组件中的状态变化可能导致Portal内组件出现意外问题。例如，将文本输入框直接放入Portal内时，若父组件触发重渲染，可能会重置输入框的自动建议，或导致其他界面异常。
为避免该问题，请将交互组件（如输入框）的状态保留在Portal内部：把Portal内容拆分为独立组件，从而隔离父组件重渲染带来的影响。
### 示例模式
```tsx
// ❌ 问题：父级状态导致重渲染，影响Portal内内容
function ParentComponent() {
const [dialogOpen, setDialogOpen] = useState(false);
const [inputValue, setInputValue] = useState(""); // State in parent
return (
<Dialog isOpen={dialogOpen} onOpenChange={setDialogOpen}>
<Dialog.Trigger>
<Button>Open Dialog</Button>
</Dialog.Trigger>
<Dialog.Portal>
<Input
value={inputValue}
onChangeText={setInputValue}
// Parent re-renders reset auto-suggestions
/>
</Dialog.Portal>
</Dialog>
);
}
// ✅ 正确：在Portal内的独立组件中管理状态
function ParentComponent() {
const [dialogOpen, setDialogOpen] = useState(false);
return (
<Dialog isOpen={dialogOpen} onOpenChange={setDialogOpen}>
<Dialog.Trigger>
<Button>Open Dialog</Button>
</Dialog.Trigger>
<Dialog.Portal>
<DialogFormContent
onClose={() => setDialogOpen(false)}
// Form state isolated from parent
/>
</Dialog.Portal>
</Dialog>
);
}
function DialogFormContent({ onClose }: { onClose: () => void }) {
const [inputValue, setInputValue] = useState(""); // State inside portal
const [error, setError] = useState("");
return (
<Dialog.Content>
<Input
value={inputValue}
onChangeText={setInputValue}
// Auto-suggestions preserved during parent re-renders
/>
<FieldError>{error}</FieldError>
<Button onPress={onClose}>Close</Button>
</Dialog.Content>
);
}
```
在正确示例中，`DialogFormContent` 独立于父组件管理自身状态。这样即便父组件因 `dialogOpen` 等变化而重渲染，也不会影响输入框的内部状态，从而保留自动建议等输入行为。
## API 参考
### PortalHost
默认情况下，所有 `Portal` 组件的子内容都会作为该 `PortalHost` 的子节点进行渲染。
| prop | type | description |
|------|----------|------------------------------------------------------------------|
| name | `string` | 作为自定义宿主使用时提供（可选） |
### Portal
| prop | type | description |
|-----------|----------|------------------------------------------------------------------|
| name* | `string` | 唯一值；同名 Portal 会替换原有 Portal |
| hostName | `string` | 子内容需要渲染到自定义宿主时提供（可选） |
| children | `React.ReactNode` | 要渲染到Portal中的内容 |
\* 必填属性
## 相关链接
- [快速开始](/docs/native/getting-started/quick-start) — 基础搭建指南
- 查阅 [Provider](/docs/native/getting-started/provider) 文档
apps/docs/content/docs/cn/native/getting-started/(handbook)/provider.mdx
+492
View File
@@ -0,0 +1,492 @@
---
title: Provider
description: 配置 HeroUI Native provider 的文本、文本输入、动画和 toast 设置
icon: chevrons-expand-horizontal
---
`HeroUINativeProvider` 是根 provider 组件，用于在你的 React Native 应用中配置和初始化 HeroUI Native。它为你的应用提供全局配置和 portal 管理。
## 概述
该 provider 是 HeroUI Native 的主要入口点，为你的应用包裹必要的上下文和配置：
- **安全区域内边距（Safe Area Insets）**：通过 `SafeAreaListener` 自动处理安全区域内边距的更新，并将其与 Uniwind 同步，以便在 Tailwind class 中使用（例如 `pb-safe-offset-3`）
- **文本配置**：全局 Text 组件设置，确保所有 HeroUI 组件保持一致
- **文本输入配置**：全局文本输入设置，确保所有 HeroUI 输入组件保持一致
- **动画配置**：全局动画控制，可禁用整个应用中的所有动画
- **Toast 配置**：全局 toast 系统配置，包括内边距、默认 props 和包裹组件
- **Portal 管理**：处理渲染在应用层级之上的浮层、模态框及其他组件
## 基础设置
用该 provider 包裹你的应用根节点：
```tsx
import { HeroUINativeProvider } from 'heroui-native';
import { GestureHandlerRootView } from 'react-native-gesture-handler';
export default function App() {
return (
<GestureHandlerRootView style={{ flex: 1 }}>
<HeroUINativeProvider>{/* 你的应用内容 */}</HeroUINativeProvider>
</GestureHandlerRootView>
);
}
```
## 配置选项
该 provider 接受一个 `config` prop，包含以下选项：
### Text 组件配置
HeroUI Native 内所有 Text 组件的全局设置。这些 props 经过精心挑选，仅包含那些适合在应用中所有 Text 组件上进行全局配置的选项：
```tsx
import { HeroUINativeProvider } from 'heroui-native';
import type { HeroUINativeConfig } from 'heroui-native';
const config: HeroUINativeConfig = {
textProps: {
// 为无障碍禁用字体缩放
allowFontScaling: false,
// 自动调整字号以适应容器
adjustsFontSizeToFit: false,
// 缩放时的最大字号倍数
maxFontSizeMultiplier: 1.5,
// 最小字体缩放比例（仅限 iOS，0.01-1.0）
minimumFontScale: 0.5,
},
};
export default function App() {
return (
<HeroUINativeProvider config={config}>
{/* 你的应用内容 */}
</HeroUINativeProvider>
);
}
```
### TextInput 组件配置
HeroUI Native 内所有基于 TextInput 的组件的全局设置（例如 Input、TextArea、SearchField、InputGroup、InputOTP）。这些 props 经过精心挑选，仅包含那些适合在应用中所有输入组件上进行全局配置的选项：
```tsx
import { HeroUINativeProvider } from 'heroui-native';
import type { HeroUINativeConfig } from 'heroui-native';
const config: HeroUINativeConfig = {
textInputProps: {
// 遵循 Text Size 无障碍设置
allowFontScaling: false,
// 启用 allowFontScaling 时的最大字号倍数
maxFontSizeMultiplier: 1.5,
},
};
export default function App() {
return (
<HeroUINativeProvider config={config}>
{/* 你的应用内容 */}
</HeroUINativeProvider>
);
}
```
<Callout type="info">
**注意**：这些 props 会作为默认值应用。直接传递给单个输入组件的任何 prop 都会覆盖对应的全局值。
</Callout>
### 动画配置
整个应用的全局动画配置：
```tsx
const config: HeroUINativeConfig = {
// 禁用应用中的所有动画（级联到所有子组件）
animation: 'disable-all',
};
```
<Callout type="warning">
**注意**：当设置为 `'disable-all'` 时，应用中的所有动画都会被禁用。这对于无障碍或性能优化很有用。
</Callout>
### 开发者信息配置
控制在控制台中显示的面向开发者的提示信息：
```tsx
const config: HeroUINativeConfig = {
devInfo: {
// 禁用样式原则提示信息
stylingPrinciples: false,
},
};
```
<Callout type="info">
**注意**：默认情况下会启用提示信息。设置 `stylingPrinciples: false` 可禁用在开发期间出现在控制台中的样式原则提示信息。
</Callout>
### Toast 配置
配置全局 toast 系统，包括内边距、默认 props 和包裹组件。你也可以完全禁用 toast provider：
**选项 1：禁用 Toast Provider**
```tsx
const config: HeroUINativeConfig = {
// 完全禁用 toast provider
toast: false,
// 或
toast: 'disabled',
};
```
<Callout type="info">
**注意**：当 toast 被禁用（`false` 或 `'disabled'`）时，`ToastProvider` 将不会被渲染，你的应用中也将无法使用 toast 功能。
</Callout>
**选项 2：配置 Toast Provider**
```tsx
import { KeyboardAvoidingView } from 'react-native';
const config: HeroUINativeConfig = {
toast: {
// 全局 toast 配置（作为所有 toast 的默认值）
defaultProps: {
variant: 'default',
placement: 'top',
isSwipeable: true,
animation: true,
},
// 与屏幕边缘间距的内边距（叠加在安全区域内边距之上）
insets: {
top: 0, // 默认值：iOS = 0，Android = 12
bottom: 6, // 默认值：iOS = 6，Android = 12
left: 12, // 默认值：12
right: 12, // 默认值：12
},
// 开始淡出透明度前可见 toast 的最大数量
maxVisibleToasts: 3,
// 用于包裹 toast 内容的自定义包裹函数
contentWrapper: (children) => (
<KeyboardAvoidingView
behavior="padding"
keyboardVerticalOffset={24}
className="flex-1"
>
{children}
</KeyboardAvoidingView>
),
},
};
```
## 完整示例
以下是展示所有配置选项的完整示例：
```tsx
import { HeroUINativeProvider } from 'heroui-native';
import type { HeroUINativeConfig } from 'heroui-native';
import { GestureHandlerRootView } from 'react-native-gesture-handler';
const config: HeroUINativeConfig = {
// 全局文本配置
textProps: {
minimumFontScale: 0.5,
maxFontSizeMultiplier: 1.5,
allowFontScaling: true,
adjustsFontSizeToFit: false,
},
// 全局文本输入配置
textInputProps: {
allowFontScaling: true,
maxFontSizeMultiplier: 1.5,
},
// 全局动画配置
animation: 'disable-all', // 可选：禁用所有动画
// 开发者信息提示配置
devInfo: {
stylingPrinciples: true, // 可选：禁用样式原则提示信息
},
// 全局 toast 配置
// 选项 1：使用自定义设置配置 toast
toast: {
defaultProps: {
variant: 'default',
placement: 'top',
},
insets: {
top: 0,
bottom: 6,
left: 12,
right: 12,
},
maxVisibleToasts: 3,
},
// 选项 2：完全禁用 toast
// toast: false,
// 或
// toast: 'disabled',
};
export default function App() {
return (
<GestureHandlerRootView style={{ flex: 1 }}>
<HeroUINativeProvider config={config}>
<YourApp />
</HeroUINativeProvider>
</GestureHandlerRootView>
);
}
```
## 与 Expo Router 集成
使用 Expo Router 时，包裹你的根布局：
```tsx
// app/_layout.tsx
import { HeroUINativeProvider } from 'heroui-native';
import type { HeroUINativeConfig } from 'heroui-native';
import { Stack } from 'expo-router';
const config: HeroUINativeConfig = {
textProps: {
minimumFontScale: 0.5,
maxFontSizeMultiplier: 1.5,
},
};
export default function RootLayout() {
return (
<HeroUINativeProvider config={config}>
<Stack />
</HeroUINativeProvider>
);
}
```
## 架构
### Provider 层级
`HeroUINativeProvider` 内部组合了多个 provider：
```
HeroUINativeProvider
├── SafeAreaListener（处理安全区域内边距更新）
│ └── GlobalAnimationSettingsProvider（动画配置）
│ └── TextComponentProvider（文本配置）
│ └── TextInputComponentProvider（文本输入配置）
│ └── ToastProvider（toast 配置，按条件渲染）
│ └── 你的应用
│ └── PortalHost（用于浮层）
```
<Callout type="info">
**注意**：`ToastProvider` 会根据 `toast` 配置按条件渲染。如果 `toast` 设置为 `false` 或 `'disabled'`，`ToastProvider` 将不会被渲染，应用内容和 `PortalHost` 会直接渲染在 `TextInputComponentProvider` 之下。
</Callout>
### 安全区域内边距处理
该 provider 会自动用来自 `react-native-safe-area-context` 的 [`SafeAreaListener`](https://appandflow.github.io/react-native-safe-area-context/api/safe-area-listener) 包裹你的应用。该组件监听安全区域内边距和框架变化而不会触发重新渲染，并通过 `onChange` 回调用最新的内边距自动更新 Uniwind。
## Raw Provider
`HeroUINativeProviderRaw` 是 `HeroUINativeProvider` 的轻量级变体，为打包体积优化而设计。它不包含 `ToastProvider` 和 `PortalHost`，为你提供一个最精简的起点，让你只安装和添加真正需要的内容。
### 何时使用
当你想完全掌控打包体积中包含哪些依赖时，使用 `HeroUINativeProviderRaw`。使用从 `heroui-native/provider-raw` 导入的 raw provider 时，以下依赖是可选的，仅在你使用对应组件时才需要：
- **react-native-screens** —— 浮层组件（Popover、Dialog）所需
- **@gorhom/bottom-sheet** —— BottomSheet 组件所需
- **react-native-svg** —— 使用图标的组件所需（Accordion、Alert、Checkbox 等）
### 设置
```tsx
import {
HeroUINativeProviderRaw,
type HeroUINativeConfigRaw,
} from 'heroui-native/provider-raw';
import { GestureHandlerRootView } from 'react-native-gesture-handler';
const config: HeroUINativeConfigRaw = {
textProps: {
maxFontSizeMultiplier: 1.5,
},
};
export default function App() {
return (
<GestureHandlerRootView style={{ flex: 1 }}>
<HeroUINativeProviderRaw config={config}>
{/* 你的应用内容 */}
</HeroUINativeProviderRaw>
</GestureHandlerRootView>
);
}
```
### 手动添加 Toast 和 Portal
如果你在使用 raw provider 时需要 toast 或 portal 功能，请自行添加：
```tsx
import { HeroUINativeProviderRaw } from 'heroui-native/provider-raw';
import { PortalHost } from 'heroui-native/portal';
import { ToastProvider } from 'heroui-native/toast';
export default function App() {
return (
<GestureHandlerRootView style={{ flex: 1 }}>
<HeroUINativeProviderRaw>
<ToastProvider>
{/* 你的应用内容 */}
<PortalHost />
</ToastProvider>
</HeroUINativeProviderRaw>
</GestureHandlerRootView>
);
}
```
### Provider 层级
```
HeroUINativeProviderRaw
├── SafeAreaListener（处理安全区域内边距更新）
│ └── GlobalAnimationSettingsProvider（动画配置）
│ └── TextComponentProvider（文本配置）
│ └── TextInputComponentProvider（文本输入配置）
│ └── 你的应用
```
## 最佳实践
### 1. 单一 Provider 实例
始终在应用根部使用单个 `HeroUINativeProvider`。不要嵌套多个 provider：
```tsx
// ❌ 不推荐
<HeroUINativeProvider>
<SomeComponent>
<HeroUINativeProvider> {/* 不要这样做 */}
<AnotherComponent />
</HeroUINativeProvider>
</SomeComponent>
</HeroUINativeProvider>
// ✅ 推荐
<HeroUINativeProvider>
<SomeComponent>
<AnotherComponent />
</SomeComponent>
</HeroUINativeProvider>
```
### 2. 配置对象
在组件外部定义你的配置，以避免每次渲染时重新创建：
```tsx
// ❌ 不推荐
function App() {
return (
<HeroUINativeProvider
config={{
textProps: {
/* 内联配置 */
},
}}
>
{/* ... */}
</HeroUINativeProvider>
);
}
// ✅ 推荐
const config: HeroUINativeConfig = {
textProps: {
maxFontSizeMultiplier: 1.5,
},
};
function App() {
return (
<HeroUINativeProvider config={config}>{/* ... */}</HeroUINativeProvider>
);
}
```
### 3. 文本配置
配置文本 props 时请考虑无障碍：
```tsx
const config: HeroUINativeConfig = {
textProps: {
// 为无障碍允许字体缩放
allowFontScaling: true,
// 但限制最大缩放比例
maxFontSizeMultiplier: 1.5,
},
};
```
## TypeScript 支持
该 provider 具有完整的类型定义。导入类型以获得更好的 IDE 支持：
```tsx
import { HeroUINativeProvider, type HeroUINativeConfig } from 'heroui-native';
const config: HeroUINativeConfig = {
// 完整的类型安全和自动补全
textProps: {
allowFontScaling: true,
maxFontSizeMultiplier: 1.5,
},
textInputProps: {
allowFontScaling: true,
maxFontSizeMultiplier: 1.5,
},
animation: 'disable-all', // 可选：禁用所有动画
devInfo: {
stylingPrinciples: true, // 可选：禁用样式原则提示信息
},
// Toast 配置选项：
// - false 或 'disabled'：禁用 toast provider
// - ToastProviderProps 对象：配置 toast 设置
toast: {
defaultProps: {
variant: 'default',
placement: 'top',
},
insets: {
top: 0,
bottom: 6,
left: 12,
right: 12,
},
},
};
```
## 相关
- [快速开始](/docs/native/getting-started/quick-start) - 基础设置指南
- [主题](/docs/native/getting-started/theming) - 自定义颜色和主题
- [样式](/docs/native/getting-started/styling) - 使用 Tailwind 为组件设置样式
apps/docs/content/docs/cn/native/getting-started/(handbook)/styling.mdx
+371
View File
@@ -0,0 +1,371 @@
---
title: 样式
description: 使用 Tailwind 或 StyleSheet API 为 HeroUI Native 组件编写样式
icon: brush
links:
themes: true
tailwind: theme
---
HeroUI Native 提供灵活的样式方案：Tailwind CSS 工具类、StyleSheet API，以及用于动态样式的 render props。
## 样式原则
HeroUI Native 以 `className` 作为主要样式入口，所有组件均可通过 `className` 使用 Tailwind 类。
**StyleSheet 优先级：** 同时传入 `style`（StyleSheet）与 `className` 时，`style` 优先级更高，可在需要时覆盖 Tailwind。
**动画样式：** 部分样式属性由 `react-native-reanimated` 驱动，与 StyleSheet 类似，其优先级也高于 `className`。要确认哪些属性受动画占用、无法仅靠 `className` 设置：
- **在 IDE 中悬停 `className`** — TypeScript 定义会提示可用属性
- **查阅组件文档** — 组件页顶部通常有样式源码链接，其中会标注动画相关限制
**自定义动画样式：** 若某属性被动画占用，可在支持 `animation` 属性的组件上通过 `animation` 进行调整。
## 基础样式
**使用 className：** 所有 HeroUI Native 组件都支持 `className`：
```tsx
import { Button } from 'heroui-native';
<Button className="bg-accent px-6 py-3 rounded-lg">
<Button.Label>Custom Button</Button.Label>
</Button>;
```
**使用 style：** 也可通过 `style` 传入内联样式：
```tsx
import { Button } from 'heroui-native';
<Button style={{ backgroundColor: '#8B5CF6', paddingHorizontal: 24 }}>
<Button.Label>Styled Button</Button.Label>
</Button>;
```
## Render Props
使用渲染函数读取组件状态并动态定制内容：
```tsx
import { RadioGroup, Label, cn } from 'heroui-native';
<RadioGroup value={value} onValueChange={setValue}>
<RadioGroup.Item value="option1">
{({ isSelected, isInvalid, isDisabled }) => (
<>
<Label
className={cn(
'text-foreground',
isSelected && 'text-accent font-semibold'
)}
>
Option 1
</Label>
<Radio
className={cn(
'border-2 rounded-full',
isSelected && 'border-accent bg-accent'
)}
>
{isSelected && <CustomIcon />}
</Radio>
</>
)}
</RadioGroup.Item>
</RadioGroup>;
```
## 封装可复用组件
结合 [tailwind-variants](https://tailwind-variants.org/)（Tailwind 优先的变体 API）封装自定义组件：
```tsx
import { Button } from 'heroui-native';
import type { ButtonRootProps } from 'heroui-native';
import { tv, type VariantProps } from 'tailwind-variants';
const customButtonVariants = tv({
base: 'font-semibold rounded-lg',
variants: {
intent: {
primary: 'bg-blue-500',
secondary: 'bg-gray-200',
danger: 'bg-red-500',
},
},
defaultVariants: {
intent: 'primary',
},
});
const customLabelVariants = tv({
base: '',
variants: {
intent: {
primary: 'text-white',
secondary: 'text-gray-800',
danger: 'text-white',
},
},
defaultVariants: {
intent: 'primary',
},
});
type CustomButtonVariants = VariantProps<typeof customButtonVariants>;
interface CustomButtonProps
extends Omit<ButtonRootProps, 'className' | 'variant'>,
CustomButtonVariants {
className?: string;
labelClassName?: string;
}
export function CustomButton({
intent,
className,
labelClassName,
children,
...props
}: CustomButtonProps) {
return (
<Button
className={customButtonVariants({ intent, className })}
{...props}
>
<Button.Label
className={customLabelVariants({ intent, className: labelClassName })}
>
{children}
</Button.Label>
</Button>
);
}
```
## 使用组件自带的 classNames
每个 HeroUI Native 组件都会导出与内部一致的 `classNames` 工具对象，便于让自定义组件在视觉上与库内组件保持一致。
例如，让自定义 `Link` 看起来像 `Button`：
```tsx
import { buttonClassNames, cn } from 'heroui-native';
import { Pressable, Text } from 'react-native';
interface LinkProps {
href: string;
variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
size?: 'sm' | 'md' | 'lg';
children: React.ReactNode;
className?: string;
}
export function Link({
href,
variant = 'primary',
size = 'md',
children,
className,
}: LinkProps) {
return (
<Pressable
className={cn(
buttonClassNames.root({ variant, size }),
className
)}
onPress={() => {
// Handle navigation
}}
>
<Text className={buttonClassNames.label({ variant, size })}>
{children}
</Text>
</Pressable>
);
}
```
**可用的 classNames 导出：**
每个组件都会导出对应的 `classNames` 对象，例如：
- `buttonClassNames` — 包含 `root` 与 `label` 函数
- `cardClassNames` — 包含 `root`、`header`、`body`、`footer`、`label` 与 `description` 函数
- `chipClassNames` — 包含 `root` 与 `label` 函数
- 其他组件同理……
**典型用法：**
```tsx
import { buttonClassNames } from 'heroui-native';
// Use with variant and size options
const rootClasses = buttonClassNames.root({
variant: 'primary',
size: 'md',
className: 'custom-class', // Optional: merge with your own classes
});
const labelClasses = buttonClassNames.label({
variant: 'primary',
size: 'md',
});
```
`classNames` 函数的变体参数与对应组件一致，便于在自定义组件与 HeroUI 组件之间保持视觉一致。
## 响应式设计
HeroUI Native 通过 [Uniwind](https://docs.uniwind.dev/breakpoints) 支持 Tailwind 的响应式断点前缀，如 `sm:`、`md:`、`lg:`、`xl:`，按屏幕宽度条件应用样式。
**移动优先：** 先写无前缀的小屏样式，再用断点为大屏增强。
### 响应式排版与间距
```tsx
import { Button } from 'heroui-native';
import { View, Text } from 'react-native';
<View className="px-4 sm:px-6 lg:px-8 py-6 sm:py-8">
<Text className="text-2xl sm:text-3xl lg:text-4xl font-bold mb-4 sm:mb-6">
Responsive Heading
</Text>
<Button className="px-3 sm:px-4 lg:px-6">
<Button.Label className="text-sm sm:text-base lg:text-lg">
Responsive Button
</Button.Label>
</Button>
</View>;
```
### 响应式布局
```tsx
import { View, Text } from 'react-native';
<View className="flex-row flex-wrap">
{/* Mobile: 1 column, Tablet: 2 columns, Desktop: 3 columns */}
<View className="w-full sm:w-1/2 lg:w-1/3 p-2">
<View className="bg-accent p-4 rounded-lg">
<Text className="text-accent-foreground">Item 1</Text>
</View>
</View>
</View>;
```
**默认断点：**
- `sm`：640px
- `md`：768px
- `lg`：1024px
- `xl`：1280px
- `2xl`：1536px
自定义断点与更多说明见 [Uniwind 断点文档](https://docs.uniwind.dev/breakpoints)。
## 工具函数
HeroUI Native 提供一些样式相关的工具。
### cn
`cn` 用于合并 Tailwind 类并处理冲突，适合条件类或与 props 传入的类合并：
```tsx
import { cn } from 'heroui-native';
import { View } from 'react-native';
function MyComponent({ className, isActive }) {
return (
<View
className={cn(
'bg-background p-4 rounded-lg',
'border border-separator',
isActive && 'bg-accent',
className
)}
/>
);
}
```
`cn` 基于 `tailwind-variants`，具备：
- 自动合并 Tailwind 类（`twMerge: true`）
- 自定义透明度分组等能力
- 合理的冲突解决（靠后的类覆盖靠前的类）
**冲突示例：**
```tsx
// 'bg-accent' overrides 'bg-background'
cn('bg-background p-4', 'bg-accent');
// Result: 'p-4 bg-accent'
```
### useThemeColor
从 CSS 变量读取主题色，支持单色或一次读取多种颜色（后者更高效）。
**单色：**
```tsx
import { useThemeColor } from 'heroui-native';
function MyComponent() {
const accentColor = useThemeColor('accent');
const dangerColor = useThemeColor('danger');
return (
<View style={{ borderColor: accentColor }}>
<Text style={{ color: dangerColor }}>Error message</Text>
</View>
);
}
```
**多色（推荐在需要多个 token 时使用）：**
```tsx
import { useThemeColor } from 'heroui-native';
function MyComponent() {
const [accentColor, backgroundColor, dangerColor] = useThemeColor([
'accent',
'background',
'danger',
]);
return (
<View style={{ borderColor: accentColor, backgroundColor }}>
<Text style={{ color: dangerColor }}>Error message</Text>
</View>
);
}
```
**类型签名：**
```tsx
// Single color
useThemeColor(themeColor: ThemeColor): string
// Multiple colors (with type inference for tuples)
useThemeColor<T extends readonly [ThemeColor, ...ThemeColor[]]>(
themeColor: T
): CreateStringTuple<T['length']>
// Multiple colors (array)
useThemeColor(themeColor: ThemeColor[]): string[]
```
可用主题色包括：`background`、`foreground`、`surface`、`accent`、`default`、`success`、`warning`、`danger` 及其 hover、soft、foreground 等变体，以及 `muted`、`border`、`separator`、`field`、`overlay` 等语义色。
## 下一步
- [动画](/docs/native/getting-started/animation)
- [主题](/docs/native/getting-started/theming)
- [颜色](/docs/native/getting-started/colors)

Some files were not shown because too many files have changed in this diff Show More