title: "@revealui/presentation" description: "57 native UI components for RevealUI - built with React 19 and Tailwind CSS v4. No external UI library dependencies (ships its own cn/cva; only tailwind-merge is a runtime..." visibility: public status: verified audience: user

@revealui/presentation

57 native UI components for RevealUI - built with React 19 and Tailwind CSS v4. No external UI library dependencies (ships its own cn/cva; only tailwind-merge is a runtime dep).

Features

• 57 Components - Forms, data display, feedback, navigation, media, and layout
• 6 Primitives - Low-level building blocks (Box, Flex, Grid, Heading, Text, Slot)
• 14 Hooks - Focus trap, click outside, popover, roving tabindex, scroll lock, and more
• Headless + Styled - Many components ship both unstyled (headless) and styled (CVA) variants
• Accessible - WCAG 2.1 patterns with proper ARIA attributes
• React 19 - Server components, hooks, and modern patterns
• Tailwind CSS v4 - Native v4 utility classes, no v3 compat layer

Installation

pnpm add @revealui/presentation

Usage

import { Button, Card, Input, Badge } from '@revealui/presentation'
import { Box, Flex } from '@revealui/presentation/primitives'
import { useClickOutside, useFocusTrap } from '@revealui/presentation/hooks'

Components (57)

Layout

| Component | Description | |-----------|-------------| | AuthLayout | Authentication page layout | | SidebarLayout | Sidebar + content layout | | StackedLayout | Stacked page layout | | Navbar | Top navigation bar | | Sidebar | Side navigation |

Form Controls

| Component | Description | |-----------|-------------| | Button / ButtonCVA | Action trigger (headless + styled) | | Input / InputCVA | Text input (headless + styled) | | Textarea / TextareaCVA | Multi-line text (headless + styled) | | Checkbox / CheckboxCVA | Checkbox (headless + styled) | | Select / SelectCVA | Dropdown select with subcomponents | | Combobox | Searchable select | | Listbox | List selection | | Radio | Radio group | | Switch | Toggle switch | | Label / FormLabel | Form labels | | Fieldset | Form field grouping |

Data Display

| Component | Description | |-----------|-------------| | Card | Content container (header, title, description, content, footer) | | Table | Data table | | Pagination | Page navigation | | Badge | Status indicator | | Text | Styled text | | Heading | Section heading | | Divider | Horizontal rule | | DescriptionList | Key-value pairs | | Breadcrumb | Navigation trail |

Feedback

| Component | Description | |-----------|-------------| | Alert | Inline alert message | | Callout | Highlighted information | | Toast | Temporary notification (with provider + hook) | | Tooltip | Hover information | | Progress | Progress bar | | Slider | Range input | | Skeleton | Loading placeholder | | EmptyState | No-data placeholder | | Stat | Metric display (with StatGroup) | | Rating | Star rating |

Navigation

| Component | Description | |-----------|-------------| | Accordion | Collapsible sections | | Tabs | Tab panels | | Stepper | Step-by-step progress | | Timeline | Chronological events | | Dropdown | Action menu | | Drawer | Slide-out panel | | Dialog | Modal dialog |

Media & Misc

| Component | Description | |-----------|-------------| | Avatar / AvatarGroup | User avatars | | CodeBlock | Syntax-highlighted code | | Kbd / KbdShortcut | Keyboard shortcut display | | Link | Styled anchor |

Primitives (6)

| Primitive | Description | |-----------|-------------| | Box | Generic container | | Flex | Flexbox layout | | Grid | CSS Grid layout | | Heading | Semantic heading | | Text | Text content | | Slot | Component composition utility |

Hooks (16)

| Hook | Purpose | |------|---------| | useClickOutside | Detect clicks outside an element | | useCloseContext | Shared close handler context | | useControllableState | Controlled/uncontrolled state | | useDataInteractive | Interactive element data attributes | | useEscapeKey | Escape key handler | | useFieldContext | Form field context (label, error, description) | | useFocusTrap | Trap focus within an element | | useLayoutAnimation | Animated layout transitions | | useLinkBehavior | Pluggable link behavior (custom router integration) | | usePopover | Popover positioning | | useRovingTabindex | Keyboard navigation in groups | | useScrollLock | Prevent body scroll | | useTheme | Theme detection (light/dark/system) | | useToggle | Boolean toggle state | | useTransition | CSS transitions | | useTypeAhead | Type-ahead search in lists |

Exports

| Subpath | Contents | |---------|----------| | @revealui/presentation | All components, primitives, and hooks | | @revealui/presentation/server | Server components | | @revealui/presentation/client | Client components | | @revealui/presentation/components | Components only | | @revealui/presentation/primitives | Primitives only | | @revealui/presentation/hooks | Hooks only | | @revealui/presentation/animations | Animation utilities | | @revealui/presentation/tokens.css | Design token CSS file |

Styled vs headless components (the *CVA convention)

Several form controls ship two implementations under a deliberate, package-wide naming convention. The bare name is the headless (Catalyst) component; the *CVA suffix is the styled, brand-token-driven one:

| Headless (bare name) | Styled (*CVA) | Source files | |----------------------|-----------------|--------------| | Button | ButtonCVA | button-headless.tsx, Button.tsx | | Input | InputCVA | input-headless.tsx, Input.tsx | | Textarea | TextareaCVA | textarea-headless.tsx, Textarea.tsx | | Checkbox | CheckboxCVA | checkbox-headless.tsx, Checkbox.tsx | | Select | SelectCVA | select-headless.tsx, Select.tsx |

• Headless (bare name): a richly composable Catalyst-style primitive with its own color / outline / plain palette system. These also power internal composites (for example, Dropdown is built on the headless Button).
• Styled (*CVA): references the semantic design tokens (bg-primary, --ring, and so on), so it re-themes automatically with the active brand. ButtonCVA is the canonical app button, imported by marketing, admin, and docs.

Which do I use? Reach for the styled *CVA component for app CTAs and forms. It is brand-aware and needs no palette wiring. Drop to the headless component only when you need Catalyst-style composition or a deliberately fixed, non-brand palette. The two are not interchangeable: Button (headless) and ButtonCVA (styled) are different components with different prop APIs, and the convention holds across all five families above.

ButtonCVA props

variant (primary, secondary, destructive, outline, ghost, link), size (sm, default, lg, icon, clear), asChild, isLoading, plus:

• automatic icon spacing (gap-2) and svg shrink / pointer-events protection, so an icon and a label compose without manual margins;
• glow: opt-in brand-glow halo for emphasis CTAs, driven by the --rvui-shadow-glow token;
• shine: opt-in subtle light sweep on hover.

import { ButtonCVA } from '@revealui/presentation/server'

<ButtonCVA variant="primary" glow>Get started</ButtonCVA>
<ButtonCVA variant="primary" size="lg" shine>Upgrade</ButtonCVA>
<ButtonCVA isLoading>Saving...</ButtonCVA>

Development

# Build
pnpm build

# Type check
pnpm typecheck

# Watch mode
pnpm dev

Adding Components

1. Create component in src/components/ (styled) or src/primitives/ (unstyled)
2. Export from the respective index.ts
3. Use CVA for variant-based styling
4. Follow WCAG 2.1 accessibility patterns

When to Use This

• You need accessible, styled UI components (buttons, forms, cards, dialogs) for a RevealUI app
• You want headless + styled variants so you can choose between full control and quick defaults
• You need React hooks for common UI patterns (focus trap, click outside, popover positioning)
• Not for CMS admin UI - @revealui/core/admin provides the admin dashboard
• Not for rich text editing - use @revealui/core/richtext/client (Lexical-based)

Design Principles

• Sovereign: No external UI library dependencies (no Radix, no shadcn). Ships its own cn + cva implementations; only tailwind-merge is a runtime dep for class conflict resolution
• Orthogonal: Components, primitives, and hooks are independent subpath exports with no cross-cutting entanglement
• Justifiable: Every component ships headless and styled variants because different contexts need different levels of control

Related

• Core Package - Runtime engine (uses presentation components)
• Architecture Guide

License

MIT