fcakyon/claude-codex-settings / plugins/heroui-skills/skills/heroui-native
heroui-native
UnverifiedHeroUI Native component library for React Native (Tailwind v4 via Uniwind). Use when building mobile UIs with HeroUI Native — creating Buttons, Cards, TextFields, Dialogs; installing heroui-native; configuring dark/light themes; or fetching component docs. Keywords: HeroUI Native, heroui-native, React Native UI, Uniwind, mobile components.
Marketplace adaptation: installation and framework guidance follow the host project.
HeroUI Native Development Guide
HeroUI Native is a component library built on Uniwind (Tailwind CSS for React Native) and React Native, providing accessible, customizable UI components for mobile applications.
Installation
This skill is provided by the marketplace plugin. Install project dependencies using the host project package manager.
CRITICAL: Native Only - Do Not Use Web Patterns
This guide is for HeroUI Native ONLY. Do NOT apply HeroUI React (web) patterns — the package, styling engine, and color format all differ:
| Feature | React (Web) | Native (Mobile) |
|---|---|---|
| Styling | Tailwind CSS v4 | Uniwind (Tailwind for React Native) |
| Colors | oklch format | HSL format |
| Package | @heroui/react | heroui-native |
| Platform | Web browsers | iOS & Android |
// CORRECT — Native pattern
import { Button } from "heroui-native";
<Button variant="primary" onPress={() => console.log("Pressed!")}>
Click me
</Button>;
Always fetch Native docs before implementing.
Core Principles
- Semantic variants (
primary,secondary,tertiary) over visual descriptions - Composition over configuration (compound components)
- Theme variables with HSL color format
- React Native StyleSheet patterns with Uniwind utilities
Accessing Documentation & Component Information
For component details, examples, props, and implementation patterns, always fetch documentation:
Using Scripts
# List all available components
node scripts/list_components.mjs
# Get component documentation (MDX)
node scripts/get_component_docs.mjs Button
node scripts/get_component_docs.mjs Button Card TextField
# Get theme variables
node scripts/get_theme.mjs
# Get non-component docs (guides, releases)
node scripts/get_docs.mjs /docs/native/getting-started/theming
Direct MDX URLs
Component docs: fetch .mdx with a concrete kebab-case slug. Run node scripts/list_components.mjs when the slug is unknown, and never fetch a URL that still contains a placeholder.
Examples:
- Button:
https://heroui.com/docs/native/components/button.mdx - Dialog:
https://heroui.com/docs/native/components/dialog.mdx - TextField:
https://heroui.com/docs/native/components/text-field.mdx
Getting started guides: use a concrete topic URL such as https://heroui.com/docs/native/getting-started/quick-start.mdx.
Important: Always fetch component docs before implementing. The MDX docs include complete examples, props, anatomy, and API references.
Installation Essentials
Quick Install
npm i heroui-native react-native-reanimated react-native-gesture-handler react-native-safe-area-context @gorhom/bottom-sheet react-native-svg react-native-worklets tailwind-merge tailwind-variants
Framework Setup (Expo - Recommended)
- Install dependencies:
npx create-expo-app MyApp
cd MyApp
npm i heroui-native uniwind tailwindcss
npm i react-native-reanimated react-native-gesture-handler react-native-safe-area-context @gorhom/bottom-sheet react-native-svg react-native-worklets tailwind-merge tailwind-variants
- Create
global.css:
@import "tailwindcss";
@import "uniwind";
@import "heroui-native/styles";
@source "./node_modules/heroui-native/lib";
- Wrap app with providers:
import { GestureHandlerRootView } from "react-native-gesture-handler";
import { HeroUINativeProvider } from "heroui-native";
import "./global.css";
export default function Layout() {
return (
<GestureHandlerRootView style={{ flex: 1 }}>
<HeroUINativeProvider>
<App />
</HeroUINativeProvider>
</GestureHandlerRootView>
);
}
Critical Setup Requirements
- Uniwind is Required - HeroUI Native uses Uniwind (Tailwind CSS for React Native)
- HeroUINativeProvider Required - Wrap your app with
HeroUINativeProvider - GestureHandlerRootView Required - Wrap with
GestureHandlerRootViewfrom react-native-gesture-handler - Use Compound Components - Components use compound structure (e.g.,
Card.Header,Card.Body) - Use onPress, not onClick - React Native uses
onPressevent handlers - Platform-Specific Code - Use
Platform.OSfor iOS/Android differences
Component Patterns
HeroUI Native uses compound component patterns. Each component has subcomponents accessed via dot notation.
Example - Card:
<Card>
<Card.Header>{/* Icons, badges */}</Card.Header>
<Card.Body>
<Card.Title>Title</Card.Title>
<Card.Description>Description</Card.Description>
</Card.Body>
<Card.Footer>{/* Actions */}</Card.Footer>
</Card>
Key Points:
- Always use compound structure - don't flatten to props
- Subcomponents are accessed via dot notation (e.g.,
Card.Header) - Native Card uses
Card.Body(notCard.Content); Title and Description go inside Body - Fetch component docs for complete anatomy and examples
Semantic Variants
HeroUI uses semantic naming to communicate functional intent:
| Variant | Purpose | Usage |
|---|---|---|
primary | Main action to move forward | 1 per context |
secondary | Alternative actions | Multiple |
tertiary | Dismissive actions (cancel, skip) | Sparingly |
danger | Destructive actions | When needed |
danger-soft | Soft destructive actions | Less prominent |
ghost | Low-emphasis actions | Minimal weight |
outline | Secondary actions | Bordered style |
Don't use raw colors - semantic variants adapt to themes and accessibility.
Theming
HeroUI Native uses CSS variables via Tailwind/Uniwind for theming. Theme colors are defined in global.css:
@theme {
--color-accent: hsl(260, 100%, 70%);
--color-accent-foreground: hsl(0, 0%, 100%);
}
Get current theme variables:
node scripts/get_theme.mjs
Access theme colors programmatically:
import { useThemeColor } from "heroui-native";
const accentColor = useThemeColor("accent");
Theme switching (Light/Dark Mode):
import { Uniwind, useUniwind } from "uniwind";
const { theme } = useUniwind();
Uniwind.setTheme(theme === "light" ? "dark" : "light");
For detailed theming, fetch: https://heroui.com/docs/native/getting-started/theming.mdx
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |