UI Components Reference

Package: @hyperauth/ui

All components accept className for style overrides. All components forward additional HTML props to their underlying element via spread unless noted.

Badge

import { Badge, badgeVariants } from '@hyperauth/ui/components/badge'

Inline label element. Renders as <span> by default. Supports asChild to merge props onto a child element via Radix Slot.

Props

Extends React.ComponentProps<'span'>.

BadgeVariant

'default' | 'secondary' | 'destructive' | 'outline' | 'ghost' | 'link'

badgeVariants

cva variant helper. Accepts { variant }. Returns a class string.

Button

import { Button, buttonVariants } from '@hyperauth/ui/components/button'

Interactive button element. Renders as <button> by default. Supports asChild.

Props

Extends React.ComponentProps<'button'>.

ButtonVariant

'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link'

ButtonSize

'default' | 'xs' | 'sm' | 'lg' | 'icon' | 'icon-xs' | 'icon-sm' | 'icon-lg'

buttonVariants

cva variant helper. Accepts { variant, size }.

Card

import {
  Card,
  CardHeader,
  CardFooter,
  CardTitle,
  CardAction,
  CardDescription,
  CardContent,
} from '@hyperauth/ui/components/card'

Compound card component. All sub-components extend React.ComponentProps<'div'>.

Command

import {
  Command,
  CommandDialog,
  CommandInput,
  CommandList,
  CommandEmpty,
  CommandGroup,
  CommandItem,
  CommandShortcut,
  CommandSeparator,
} from '@hyperauth/ui/components/command'

Command palette components built on cmdk.

Command

Extends React.ComponentProps<typeof CommandPrimitive> (cmdk root).

CommandDialog

Extends React.ComponentProps<typeof Dialog>.

CommandInput

Extends React.ComponentProps<typeof CommandPrimitive.Input>.

CommandList

Extends React.ComponentProps<typeof CommandPrimitive.List>. Max height: 300px.

CommandEmpty

Extends React.ComponentProps<typeof CommandPrimitive.Empty>.

CommandGroup

Extends React.ComponentProps<typeof CommandPrimitive.Group>.

CommandItem

Extends React.ComponentProps<typeof CommandPrimitive.Item>.

CommandSeparator

Extends React.ComponentProps<typeof CommandPrimitive.Separator>.

CommandShortcut

Extends React.ComponentProps<'span'>. Right-aligned muted keyboard shortcut display.

Dialog

import {
  Dialog,
  DialogTrigger,
  DialogPortal,
  DialogOverlay,
  DialogClose,
  DialogContent,
  DialogHeader,
  DialogFooter,
  DialogTitle,
  DialogDescription,
} from '@hyperauth/ui/components/dialog'

Modal dialog components built on Radix UI Dialog primitive.

Dialog

Extends React.ComponentProps<typeof DialogPrimitive.Root>.

DialogTrigger

Extends React.ComponentProps<typeof DialogPrimitive.Trigger>.

DialogPortal

Extends React.ComponentProps<typeof DialogPrimitive.Portal>.

DialogOverlay

Extends React.ComponentProps<typeof DialogPrimitive.Overlay>.

DialogClose

Extends React.ComponentProps<typeof DialogPrimitive.Close>.

DialogContent

Extends React.ComponentProps<typeof DialogPrimitive.Content>.

DialogHeader

Extends React.ComponentProps<'div'>.

DialogFooter

Extends React.ComponentProps<'div'>.

DialogTitle

Extends React.ComponentProps<typeof DialogPrimitive.Title>.

DialogDescription

Extends React.ComponentProps<typeof DialogPrimitive.Description>.

Input

import { Input } from '@hyperauth/ui/components/input'

Styled text input. Extends React.ComponentProps<'input'>. No additional props beyond standard <input> attributes.

InputGroup

import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupText,
  InputGroupInput,
  InputGroupTextarea,
} from '@hyperauth/ui/components/input-group'

Composite input with inline addons.

InputGroup

Container. Extends React.ComponentProps<'div'>. Sets role="group".

InputGroupAddon

Extends React.ComponentProps<'div'>.

AddonAlign

'inline-start' | 'inline-end' | 'block-start' | 'block-end'

InputGroupButton

Extends Omit<React.ComponentProps<typeof Button>, 'size'>.

InputGroupButtonSize

'xs' | 'sm' | 'icon-xs' | 'icon-sm'

InputGroupText

Extends React.ComponentProps<'span'>. Muted text element inside the group.

InputGroupInput

Extends React.ComponentProps<'input'>. Sets data-slot="input-group-control".

InputGroupTextarea

Extends React.ComponentProps<'textarea'>. Sets data-slot="input-group-control".

Label

import { Label } from '@hyperauth/ui/components/label'

Extends React.ComponentProps<typeof LabelPrimitive.Root> (Radix UI Label). No additional props.

Logo

import { Logo } from '@hyperauth/ui/components/logo'

HyperAuth SVG logo mark.

Props

Extends React.SVGProps<SVGSVGElement>.

Sets aria-hidden="true". viewBox="0 0 164 164".

PasskeyIcon

import { PasskeyIcon } from '@hyperauth/ui/components/passkey-icon'

Passkey SVG icon.

Props

Extends React.SVGProps<SVGSVGElement>.

Sets aria-hidden="true". viewBox="0 0 24 24".

Popover

import {
  Popover,
  PopoverTrigger,
  PopoverContent,
  PopoverAnchor,
  PopoverHeader,
  PopoverTitle,
  PopoverDescription,
} from '@hyperauth/ui/components/popover'

Floating popover built on Radix UI Popover primitive. Marked "use client".

Popover

Extends React.ComponentProps<typeof PopoverPrimitive.Root>.

PopoverTrigger

Extends React.ComponentProps<typeof PopoverPrimitive.Trigger>.

PopoverContent

Extends React.ComponentProps<typeof PopoverPrimitive.Content>.

Renders inside a PopoverPrimitive.Portal.

PopoverAnchor

Extends React.ComponentProps<typeof PopoverPrimitive.Anchor>.

PopoverHeader

Extends React.ComponentProps<'div'>.

PopoverTitle

Extends React.ComponentProps<'h2'>. Renders as <div>.

PopoverDescription

Extends React.ComponentProps<'p'>.

ScrollArea

import { ScrollArea, ScrollBar } from '@hyperauth/ui/components/scroll-area'

Custom scrollable container built on Radix UI ScrollArea primitive.

ScrollArea

Extends React.ComponentProps<typeof ScrollAreaPrimitive.Root>.

ScrollBar

Extends React.ComponentProps<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>.

Separator

import { Separator } from '@hyperauth/ui/components/separator'

Visual divider. Marked "use client". Built on Radix UI Separator primitive.

Props

Extends React.ComponentProps<typeof SeparatorPrimitive.Root>.

Status

import { Status, StatusIndicator, StatusLabel, statusVariants } from '@hyperauth/ui/components/status'

Status badge with animated indicator dot.

Status

interface StatusProps extends VariantProps<typeof statusVariants>, React.ComponentProps<'div'> {
  asChild?: boolean;
}

StatusVariant

'default' | 'success' | 'error' | 'warning' | 'info'

StatusIndicator

Extends React.ComponentProps<'div'>. Animated ping dot. Sets data-slot="status-indicator".

StatusLabel

Extends React.ComponentProps<'div'>. Sets data-slot="status-label".

statusVariants

cva variant helper. Accepts { variant }.

TextMorph

import { TextMorph } from '@hyperauth/ui/components/text-morph'

Animated text with character-level layout transitions via Framer Motion.

Props

type TextMorphProps = {
  children: string;
  as?: React.ElementType;
  className?: string;
  style?: React.CSSProperties;
  variants?: Variants;
  transition?: Transition;
}

Default variants: { initial: { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0 } }.

Default transition: { type: 'spring', stiffness: 280, damping: 18, mass: 0.3 }.

Sets aria-label={children} on the root element. Individual characters set aria-hidden="true".

Textarea

import { Textarea } from '@hyperauth/ui/components/textarea'

Styled textarea. Extends React.ComponentProps<'textarea'>. No additional props. Auto-sizes via field-sizing-content. Minimum height: min-h-16.

Timeline

import {
  Timeline,
  TimelineItem,
  TimelineDot,
  TimelineConnector,
  TimelineContent,
  TimelineHeader,
  TimelineTitle,
  TimelineDescription,
  TimelineTime,
} from '@hyperauth/ui/components/timeline'

Compound timeline component with store-managed item registration and automatic status derivation. Marked "use client".

Timeline

interface TimelineProps extends React.ComponentProps<'div'> {
  asChild?: boolean;
  dir?: 'ltr' | 'rtl';
  orientation?: 'vertical' | 'horizontal';
  variant?: 'default' | 'alternate';
  activeIndex?: number;
}

Sets role="list" and aria-orientation.

TimelineItem

Extends React.ComponentProps<'div'>. Accepts asChild.

Sets role="listitem". Sets aria-current="step" when status === 'active'. Sets data-status to the derived item status.

TimelineDot

Extends React.ComponentProps<'div'>. Accepts asChild. Sets data-status.

Visual indicator dot. Border color reflects item status: border-primary for 'completed' and 'active', border-border for 'pending'.

TimelineConnector

Extends React.ComponentProps<'div'>. Accepts asChild.

Sets aria-hidden="true". Not rendered on the last item unless forceMount is set. Connector is colored bg-primary when the next item's status is 'completed' or 'active'.

TimelineContent

Extends React.ComponentProps<'div'>. Accepts asChild. Sets data-status.

TimelineHeader

Extends React.ComponentProps<'div'>. Accepts asChild.

TimelineTitle

Extends React.ComponentProps<'div'>. Accepts asChild.

TimelineDescription

Extends React.ComponentProps<'div'>. Accepts asChild.

TimelineTime

interface TimelineTimeProps extends React.ComponentProps<'time'> {
  asChild?: boolean;
}

Renders as <time> by default.

VisuallyHiddenInput

import { VisuallyHiddenInput } from '@hyperauth/ui/components/visually-hidden-input'

Renders a visually hidden <input> that mirrors the value of a visible control element. Used to bridge custom UI controls into native form submission. Marked "use client".

Props

interface VisuallyHiddenInputProps<T = string | string[]>
  extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'value' | 'checked' | 'onReset'> {
  value?: T;
  checked?: boolean;
  control: HTMLElement | null;
  bubbles?: boolean;
}

The element is absolutely positioned off-screen. When control is provided, its dimensions are observed via ResizeObserver and reflected on the hidden input.

Hooks

useAsRef

import { useAsRef } from '@hyperauth/ui/hooks/use-as-ref'

function useAsRef<T>(props: T): React.RefObject<T>

Stores a value in a ref and keeps it current via useIsomorphicLayoutEffect. Returns a ref whose .current always reflects the latest value without triggering re-renders.

useIsomorphicLayoutEffect

import { useIsomorphicLayoutEffect } from '@hyperauth/ui/hooks/use-isomorphic-layout-effect'

const useIsomorphicLayoutEffect: typeof React.useEffect

React.useLayoutEffect in browser environments, React.useEffect in server/SSR environments. Prevents the useLayoutEffect does nothing on the server warning.

useLazyRef

import { useLazyRef } from '@hyperauth/ui/hooks/use-lazy-ref'

function useLazyRef<T>(fn: () => T): React.RefObject<T>

Creates a ref whose initial value is computed once from fn on first render. Subsequent renders return the same ref without re-running fn.

Utility

cn

import { cn } from '@hyperauth/ui/lib/utils'

function cn(...inputs: ClassValue[]): string

Merges Tailwind CSS class names using clsx and tailwind-merge. Resolves conflicting utility classes in favor of the last class.