# HeroUI v3 Native Documentation

> Documentation for HeroUI Native component library.

HeroUI Native is a component library built on [Tailwind v4](https://tailwindcss.com/) via [Uniwind](https://uniwind.dev/) and modern mobile development technologies. Every component comes with smooth animations, polished details, and built-in accessibility—ready to use, fully customizable.

**Key Features:**

- Beautiful by default - Professional look out of the box
- Accessible - Built with accessibility best practices
- Flexible - Customizable components with predictable patterns
- Developer-friendly - Fully typed APIs and excellent autocompletion

## Documentation Index

### Components

- [All Components](https://www.heroui.com/en/docs/native/components): Explore the full list of components available in HeroUI Native. More are on the way.
- [Button](https://www.heroui.com/en/docs/native/components/button): Interactive component that triggers an action when pressed.
- [CloseButton](https://www.heroui.com/en/docs/native/components/close-button): Button component for closing dialogs, modals, or dismissing content.
- [LinkButton](https://www.heroui.com/en/docs/native/components/link-button): A ghost-variant button with no highlight feedback, designed for inline link-style interactions.
- [Menu](https://www.heroui.com/en/docs/native/components/menu): A floating context menu with positioning, selection groups, and multiple presentation modes.
- [TagGroup](https://www.heroui.com/en/docs/native/components/tag-group): A compound component for displaying and managing selectable tags with optional removal.
- [Slider](https://www.heroui.com/en/docs/native/components/slider): A draggable input for selecting a value or range within a bounded interval.
- [Switch](https://www.heroui.com/en/docs/native/components/switch): A toggle control that allows users to switch between on and off states.
- [Chip](https://www.heroui.com/en/docs/native/components/chip): Displays a compact element in a capsule shape.
- [Alert](https://www.heroui.com/en/docs/native/components/alert): Displays important messages and notifications to users with status indicators.
- [SkeletonGroup](https://www.heroui.com/en/docs/native/components/skeleton-group): Coordinates multiple skeleton loading placeholders with centralized animation control.
- [Skeleton](https://www.heroui.com/en/docs/native/components/skeleton): Displays a loading placeholder with shimmer or pulse animation effects.
- [Spinner](https://www.heroui.com/en/docs/native/components/spinner): Displays an animated loading indicator.
- [Checkbox](https://www.heroui.com/en/docs/native/components/checkbox): A selectable control that allows users to toggle between checked and unchecked states.
- [ControlField](https://www.heroui.com/en/docs/native/components/control-field): A field component that combines a label, description (or other content), and a control component (Switch or Checkbox) into a single pressable area.
- [Description](https://www.heroui.com/en/docs/native/components/description): Text component for providing accessible descriptions and helper text for form fields and other UI elements.
- [FieldError](https://www.heroui.com/en/docs/native/components/field-error): Displays validation error message content with smooth animations.
- [InputGroup](https://www.heroui.com/en/docs/native/components/input-group): A compound layout component that groups an input with optional prefix and suffix decorators.
- [InputOTP](https://www.heroui.com/en/docs/native/components/input-otp): Input component for entering one-time passwords (OTP) with individual character slots, animations, and validation support.
- [Input](https://www.heroui.com/en/docs/native/components/input): A text input component with styled border and background for collecting user input.
- [Label](https://www.heroui.com/en/docs/native/components/label): Text component for labeling form fields and other UI elements with support for required indicators and validation states.
- [RadioGroup](https://www.heroui.com/en/docs/native/components/radio-group): A set of radio buttons where only one option can be selected at a time.
- [SearchField](https://www.heroui.com/en/docs/native/components/search-field): A compound search input for filtering and querying content.
- [Select](https://www.heroui.com/en/docs/native/components/select): Displays a list of options for the user to pick from — triggered by a button.
- [TextArea](https://www.heroui.com/en/docs/native/components/text-area): A multiline text input component with styled border and background for collecting longer user input.
- [TextField](https://www.heroui.com/en/docs/native/components/text-field): A text input component with label, description, and error handling for collecting user input.
- [Card](https://www.heroui.com/en/docs/native/components/card): Displays a card container with flexible layout sections for structured content.
- [Separator](https://www.heroui.com/en/docs/native/components/separator): A simple line to separate content visually.
- [Surface](https://www.heroui.com/en/docs/native/components/surface): Container component that provides elevation and background styling.
- [Avatar](https://www.heroui.com/en/docs/native/components/avatar): Displays a user avatar with support for images, text initials, or fallback icons.
- [Accordion](https://www.heroui.com/en/docs/native/components/accordion): A collapsible content panel for organizing information in a compact space
- [ListGroup](https://www.heroui.com/en/docs/native/components/list-group): A Surface-based container that groups related list items with consistent layout and spacing.
- [Tabs](https://www.heroui.com/en/docs/native/components/tabs): Organize content into tabbed views with animated transitions and indicators.
- [BottomSheet](https://www.heroui.com/en/docs/native/components/bottom-sheet): Displays a bottom sheet that slides up from the bottom with animated transitions and swipe-to-dismiss gestures.
- [Dialog](https://www.heroui.com/en/docs/native/components/dialog): Displays a modal overlay with animated transitions and gesture-based dismissal.
- [Popover](https://www.heroui.com/en/docs/native/components/popover): Displays a floating content panel anchored to a trigger element with placement and alignment options.
- [Toast](https://www.heroui.com/en/docs/native/components/toast): Displays temporary notification messages that appear at the top or bottom of the screen.
- [Typography](https://www.heroui.com/en/docs/native/components/text): Primitive typography component for rendering styled text with semantic type variants.
- [PressableFeedback](https://www.heroui.com/en/docs/native/components/pressable-feedback): Container component that provides visual feedback for press interactions with automatic scale animation.
- [ScrollShadow](https://www.heroui.com/en/docs/native/components/scroll-shadow): Adds dynamic gradient shadows to scrollable content based on scroll position and overflow.
- [所有组件](https://www.heroui.com/cn/docs/native/components): 浏览 HeroUI Native 提供的全部组件；更多组件将陆续推出。
- [Button 按钮](https://www.heroui.com/cn/docs/native/components/button): 按下时触发操作的交互组件。
- [CloseButton 关闭按钮](https://www.heroui.com/cn/docs/native/components/close-button): 用于关闭对话框、模态框或收起内容的按钮组件。
- [LinkButton 链接按钮](https://www.heroui.com/cn/docs/native/components/link-button): 幽灵样式按钮，无高亮按压反馈，适合行内链接式交互。
- [Menu 菜单](https://www.heroui.com/cn/docs/native/components/menu): 浮动上下文菜单，支持定位、选择分组与多种呈现方式。
- [TagGroup 标签组](https://www.heroui.com/cn/docs/native/components/tag-group): 用于展示与管理可选标签的复合组件，支持可选移除。
- [Slider 滑块](https://www.heroui.com/cn/docs/native/components/slider): 在有限区间内通过拖拽选择单个值或区间的输入控件。
- [Switch 开关](https://www.heroui.com/cn/docs/native/components/switch): 在开与关两种状态之间切换的拨动控件。
- [Chip 标签](https://www.heroui.com/cn/docs/native/components/chip): 以胶囊形态展示的小型元素。
- [Alert 警告](https://www.heroui.com/cn/docs/native/components/alert): 向用户展示重要消息与通知，并带有状态指示。
- [SkeletonGroup 骨架屏组](https://www.heroui.com/cn/docs/native/components/skeleton-group): 协调多个骨架屏占位，并提供统一的动画与加载态控制。
- [Skeleton 骨架屏](https://www.heroui.com/cn/docs/native/components/skeleton): 展示加载占位，支持微光（shimmer）或脉冲（pulse）等动画效果。
- [Spinner 加载指示器](https://www.heroui.com/cn/docs/native/components/spinner): 展示旋转加载动画。
- [Checkbox 复选框](https://www.heroui.com/cn/docs/native/components/checkbox): 可在选中与未选中之间切换的可选控件。
- [ControlField 控件字段](https://www.heroui.com/cn/docs/native/components/control-field): 将标签、说明（或其他内容）与控件（Switch 或 Checkbox）组合为单一可按压区域的字段组件。
- [Description 描述](https://www.heroui.com/cn/docs/native/components/description): 用于为表单字段等提供无障碍说明与辅助文案的文本组件。
- [FieldError 字段错误](https://www.heroui.com/cn/docs/native/components/field-error): 展示校验错误信息，并带有平滑动画。
- [InputGroup 输入框组](https://www.heroui.com/cn/docs/native/components/input-group): 复合布局组件，将输入框与可选的前后缀装饰组合在一起。
- [InputOTP 一次性密码输入框](https://www.heroui.com/cn/docs/native/components/input-otp): 用于输入一次性验证码（OTP）的输入组件，支持分格、动画与校验。
- [Input 输入框](https://www.heroui.com/cn/docs/native/components/input): 单行文本输入，带样式边框与背景，用于收集用户输入。
- [Label 标签](https://www.heroui.com/cn/docs/native/components/label): 用于标注表单字段等 UI 的文本组件，支持必填标记与校验状态。
- [RadioGroup 单选框组](https://www.heroui.com/cn/docs/native/components/radio-group): 单选按钮组，同一时间只能选中一个选项。
- [SearchField 搜索框](https://www.heroui.com/cn/docs/native/components/search-field): 用于筛选与查询的复合搜索输入框。
- [Select 选择器](https://www.heroui.com/cn/docs/native/components/select): 通过按钮触发，展示可选列表供用户选择。
- [TextArea 多行文本框](https://www.heroui.com/cn/docs/native/components/text-area): 多行文本输入，带样式边框与背景，用于收集较长内容。
- [TextField 文本输入框](https://www.heroui.com/cn/docs/native/components/text-field): 带标签、说明与错误处理的文本输入，用于收集用户输入。
- [Card 卡片](https://www.heroui.com/cn/docs/native/components/card): 卡片容器，提供灵活分区以结构化展示内容。
- [Separator 分隔符](https://www.heroui.com/cn/docs/native/components/separator): 用于在视觉上分隔内容的简单线条。
- [Surface 表面](https://www.heroui.com/cn/docs/native/components/surface): 提供层级与背景样式的容器组件。
- [Avatar 头像](https://www.heroui.com/cn/docs/native/components/avatar): 展示用户头像，支持图片、文字首字母或回退图标。
- [Accordion 手风琴](https://www.heroui.com/cn/docs/native/components/accordion): 可折叠内容面板，在紧凑空间内组织信息
- [ListGroup 列表组](https://www.heroui.com/cn/docs/native/components/list-group): 基于 Surface 的容器，用于分组展示列表项并保持一致的布局与间距。
- [Tabs 标签页](https://www.heroui.com/cn/docs/native/components/tabs): 使用选项卡视图组织内容，支持动画过渡与指示器。
- [BottomSheet 底部弹层](https://www.heroui.com/cn/docs/native/components/bottom-sheet): 自底部滑入的底部表单，带动画与下滑关闭手势。
- [Dialog 对话框](https://www.heroui.com/cn/docs/native/components/dialog): 模态浮层，带动画过渡并支持手势关闭。
- [Popover 弹出框](https://www.heroui.com/cn/docs/native/components/popover): 锚定在触发器上的浮动内容面板，支持方位与对齐选项。
- [Toast 轻提示](https://www.heroui.com/cn/docs/native/components/toast): 在屏幕顶部或底部展示的临时通知消息。
- [Typography 文本](https://www.heroui.com/cn/docs/native/components/text): 用于渲染带语义类型变体的样式化文本的排版基元组件。
- [PressableFeedback 按压反馈](https://www.heroui.com/cn/docs/native/components/pressable-feedback): 为按压交互提供视觉反馈的容器组件，内置缩放动画。
- [ScrollShadow 滚动阴影](https://www.heroui.com/cn/docs/native/components/scroll-shadow): 根据滚动位置与溢出情况，为可滚动内容添加动态渐变边缘阴影。

### Getting-started

- [Introduction](https://www.heroui.com/en/docs/native/getting-started): An open-source UI component library for building beautiful and accessible user interfaces.
- [Animation](https://www.heroui.com/en/docs/native/getting-started/animation): Add smooth animations and transitions to HeroUI Native components
- [Colors](https://www.heroui.com/en/docs/native/getting-started/colors): Color palette and theming system for HeroUI Native
- [Composition](https://www.heroui.com/en/docs/native/getting-started/composition): Build flexible UI with component composition patterns
- [Portal](https://www.heroui.com/en/docs/native/getting-started/portal)
- [Provider](https://www.heroui.com/en/docs/native/getting-started/provider): Configure HeroUI Native provider with text, animation, and toast settings
- [Styling](https://www.heroui.com/en/docs/native/getting-started/styling): Style HeroUI Native components with Tailwind or StyleSheet API
- [Theming](https://www.heroui.com/en/docs/native/getting-started/theming): Customize HeroUI Native's design system with CSS variables and global styles
- [Design Principles](https://www.heroui.com/en/docs/native/getting-started/design-principles): Core principles that guide HeroUI v3's design and development
- [Quick Start](https://www.heroui.com/en/docs/native/getting-started/quick-start): Get up and running with HeroUI Native
- [Agent Skills](https://www.heroui.com/en/docs/native/getting-started/agent-skills): Enable AI assistants to build mobile UIs with HeroUI Native components
- [AGENTS.md](https://www.heroui.com/en/docs/native/getting-started/agents-md): Download HeroUI Native documentation for AI coding agents
- [LLMs.txt](https://www.heroui.com/en/docs/native/getting-started/llms-txt): Enable AI assistants like Claude, Cursor, and Windsurf to understand HeroUI Native
- [MCP Server](https://www.heroui.com/en/docs/native/getting-started/mcp-server): Access HeroUI Native documentation directly in your AI assistant
- [介绍](https://www.heroui.com/cn/docs/native/getting-started): 开源 React Native UI 组件库，用于构建美观且易于访问的移动界面。
- [动画](https://www.heroui.com/cn/docs/native/getting-started/animation): 为 HeroUI Native 组件添加流畅动画与过渡
- [颜色](https://www.heroui.com/cn/docs/native/getting-started/colors): HeroUI Native 的调色板与主题系统
- [组合](https://www.heroui.com/cn/docs/native/getting-started/composition): 用组件组合模式搭建灵活 UI
- [Portal](https://www.heroui.com/cn/docs/native/getting-started/portal)
- [Provider](https://www.heroui.com/cn/docs/native/getting-started/provider): 配置 HeroUI Native 的文本、动画与 Toast 等全局能力
- [样式](https://www.heroui.com/cn/docs/native/getting-started/styling): 使用 Tailwind 或 StyleSheet API 为 HeroUI Native 组件编写样式
- [主题](https://www.heroui.com/cn/docs/native/getting-started/theming): 使用 CSS 变量与全局样式定制 HeroUI Native 设计系统
- [设计原则](https://www.heroui.com/cn/docs/native/getting-started/design-principles): 指导 HeroUI Native 设计与开发的核心理念
- [快速开始](https://www.heroui.com/cn/docs/native/getting-started/quick-start): 几分钟内上手 HeroUI Native
- [Agent Skills](https://www.heroui.com/cn/docs/native/getting-started/agent-skills): 让 AI 助手使用 HeroUI Native 组件构建移动端界面
- [AGENTS.md](https://www.heroui.com/cn/docs/native/getting-started/agents-md): 将 HeroUI Native 文档下载到项目中，供 AI 编程助手引用
- [LLMs.txt](https://www.heroui.com/cn/docs/native/getting-started/llms-txt): 让 Claude、Cursor、Windsurf 等 AI 助手理解 HeroUI Native 文档
- [MCP 服务器](https://www.heroui.com/cn/docs/native/getting-started/mcp-server): 在 AI 助手中直接访问 HeroUI Native 文档

### Releases

- [Beta 10](https://www.heroui.com/en/docs/native/releases/beta-10): Bottom Sheet component, PressableFeedback refactor, Animation API State Prop extension, use-theme-color multiple colors selection, and bug fixes.
- [Beta 11](https://www.heroui.com/en/docs/native/releases/beta-11): Enhanced Bottom Sheet close coordination, Dialog swipe-to-dismiss fixes, TextField improvements, and PortalHost export for advanced use cases
- [Beta 12](https://www.heroui.com/en/docs/native/releases/beta-12): InputOTP, Label, and Description components, Popover close fixes, controlled state improvements, border radius fixes, and variant style prop support
- [Beta 13](https://www.heroui.com/en/docs/native/releases/beta-13): TextArea component, Button outline variant, Tabs improvements, form component decomposition, popup animation refactor, style class exports, and critical bug fixes
- [create-heroui-native-app](https://www.heroui.com/en/docs/native/releases/create-heroui-native-app): New CLI for scaffolding a preconfigured HeroUI Native + Expo Router project — Expo SDK 56, React Native 0.85, Uniwind, all peer dependencies wired up, two starter templates (single-screen and tabs).
- [All Releases](https://www.heroui.com/en/docs/native/releases): All updates and changes to HeroUI Native, including new features, fixes, and breaking changes.
- [RC 1](https://www.heroui.com/en/docs/native/releases/rc-1): Alert component, standalone Radio component, Select TriggerIndicator, HeroUINativeProviderRaw, disableFullWindowOverlay prop, styles prop expansion, theme surface refactor
- [RC 2](https://www.heroui.com/en/docs/native/releases/rc-2): SearchField, ListGroup, and Slider components, Select multi-selection mode, Button feedback API refactor, peer dependency relaxation
- [RC 3](https://www.heroui.com/en/docs/native/releases/rc-3): TagGroup, Menu, and InputGroup components, Bottom Sheet Android back press fix, Expo 55 compatibility
- [RC 4](https://www.heroui.com/en/docs/native/releases/rc-4): SubMenu component, Slider Output composition, PressableFeedback ripple fix, Bottom Sheet back handler fix
- [v1.0.0](https://www.heroui.com/en/docs/native/releases/v1-0-0): LinkButton component, sub-menu conflict resolution, optional @gorhom/bottom-sheet, ThemeColorValue branded type
- [v1.0.1](https://www.heroui.com/en/docs/native/releases/v1-0-1): Toast race condition fix, disabled state styling with disabled modifier, backdrop style variable
- [v1.0.2](https://www.heroui.com/en/docs/native/releases/v1-0-2): asChild slot pattern for PressableFeedback and Surface, Portal accessibility modal prop, Button Android variant fix, Input and Select style refinements
- [v1.0.3](https://www.heroui.com/en/docs/native/releases/v1-0-3): New Text typography component, ScrollShadow inverted support, Tabs RTL indicator fix, optional Avatar alt prop, Select indicator unification, and form field style refinements
- [v1.0.4](https://www.heroui.com/en/docs/native/releases/v1-0-4): Typography component renames Text, refined soft-foreground theme tokens with optional vibrant palette, iOS native modal offset guidance, Expo 56 / React Native 0.85 example upgrade
- [Beta 10](https://www.heroui.com/cn/docs/native/releases/beta-10): Bottom Sheet 组件、PressableFeedback 重构、动画 API 的 State 扩展、use-theme-color 多色选取与问题修复
- [Beta 11](https://www.heroui.com/cn/docs/native/releases/beta-11): Bottom Sheet 关闭协同增强、Dialog 侧滑关闭修复、TextField 改进，以及面向高级场景的 PortalHost 导出
- [Beta 12](https://www.heroui.com/cn/docs/native/releases/beta-12): InputOTP、Label、Description 组件，Popover 关闭修复，受控状态改进，圆角修复，以及变体样式属性支持
- [Beta 13](https://www.heroui.com/cn/docs/native/releases/beta-13): TextArea 组件、Button outline 变体、Tabs 改进、表单原语拆分、弹层动画重构、样式类名导出与关键问题修复
- [create-heroui-native-app](https://www.heroui.com/cn/docs/native/releases/create-heroui-native-app): 全新的命令行工具，用于一键创建预先配置好的 HeroUI Native + Expo Router 项目 —— Expo SDK 56、React Native 0.85、Uniwind，所有 peer 依赖均已就绪，并提供两套起始模板（单页面与 Tabs）。
- [所有版本](https://www.heroui.com/cn/docs/native/releases): HeroUI Native 的全部更新与变更，包括新功能、问题修复与破坏性变更。
- [RC 1](https://www.heroui.com/cn/docs/native/releases/rc-1): Alert 组件、独立 Radio 组件、Select TriggerIndicator、HeroUINativeProviderRaw、disableFullWindowOverlay、styles 属性扩展、主题 surface 重构
- [RC 2](https://www.heroui.com/cn/docs/native/releases/rc-2): SearchField、ListGroup、Slider 组件，Select 多选模式，Button 反馈 API 重构，放宽对等依赖约束
- [RC 3](https://www.heroui.com/cn/docs/native/releases/rc-3): TagGroup、Menu、InputGroup 组件，Bottom Sheet Android 返回键修复，Expo 55 兼容
- [RC 4](https://www.heroui.com/cn/docs/native/releases/rc-4): SubMenu 组件、Slider Output 组合重构、PressableFeedback 水波纹修复、Bottom Sheet 返回键处理修复
- [v1.0.0](https://www.heroui.com/cn/docs/native/releases/v1-0-0): LinkButton 组件、子菜单冲突处理、可选的 @gorhom/bottom-sheet 对等依赖、ThemeColorValue 品牌类型
- [v1.0.1](https://www.heroui.com/cn/docs/native/releases/v1-0-1): Toast 竞态修复、使用 disabled 修饰符的禁用态样式、背景层样式变量 backdrop
- [v1.0.2](https://www.heroui.com/cn/docs/native/releases/v1-0-2): PressableFeedback 与 Surface 的 asChild 插槽模式、Portal 无障碍 modal 属性、Button Android 变体修复、Input 与 Select 样式微调
- [v1.0.3](https://www.heroui.com/cn/docs/native/releases/v1-0-3): 全新 Text 排版组件、ScrollShadow 反向列表支持、Tabs RTL 指示器修复、Avatar alt 属性可选化、Select 指示器统一、表单字段样式微调
- [v1.0.4](https://www.heroui.com/cn/docs/native/releases/v1-0-4): Typography 组件替代 Text、调整后的柔和前景色主题令牌与可选鲜亮配色、iOS 原生模态偏移说明、示例应用升级至 Expo 56 / React Native 0.85