component-patterns

UI Component Patterns

Navigation Patterns

Sidebar Navigation

Best for: complex apps with 5+ sections (dashboards, admin panels, SaaS tools).

• Width: 240-280px expanded, 64px collapsed (icon-only mode)
• Structure: logo/brand → primary nav items (icon + label) → spacer → secondary items → user menu
• Active state: bg-accent text-accent-foreground with left border accent or rounded background
• Collapsible: toggle button at bottom or top, persist preference in localStorage
• Mobile: slide-in Sheet overlay triggered by hamburger menu

Top Navigation

Best for: simpler apps with 3-5 sections, marketing sites, content platforms.

• Height: 56-64px (h-14 to h-16)
• Structure: logo (left) → nav links (center or left-aligned) → actions (right: search, notifications, user avatar)
• Active link: font-medium text-foreground vs inactive text-muted-foreground
• Dropdown menus for subsections using shadcn DropdownMenu
• Sticky: sticky top-0 z-50 bg-background/95 backdrop-blur

Breadcrumbs

Required for: hierarchies deeper than 2 levels.

• Use shadcn Breadcrumb component with separator chevrons
• Truncate middle items with "..." for deep paths (show first, last 2)
• Each segment is a clickable link except the current page

Data Display

Stats/KPI Cards

• Layout: 3-4 cards in a responsive grid (grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4)
• Structure: label (text-sm, muted) → value (text-2xl, bold) → trend indicator (green up / red down arrow + percentage)
• Optional: sparkline chart, comparison to previous period
• Animate value on appear: Framer Motion animate={{ opacity: 1, y: 0 }} with stagger

Data Tables

• Use shadcn DataTable pattern with TanStack Table
• Features: column sorting (click header), text search (filter input above), pagination (bottom)
• Row actions: kebab menu (DropdownMenu) on the right column
• Empty state: centered message in the table body area, not replacing the table
• Loading: skeleton rows matching the table structure

Card Grids

• Responsive: grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-6
• Card structure: image/icon (top) → title → description (2-line clamp) → metadata footer
• Hover: hover:shadow-md transition-shadow + subtle hover:scale-[1.02] via Framer Motion
• Stagger enter animation: each card delays 50ms after the previous

Lists with Avatars

• Row height: consistent py-3 to py-4 per item
• Structure: avatar (40px circle) → name + subtitle (stacked) → metadata (right-aligned) → action button
• Dividers: divide-y on the container, not manual borders
• Interactive rows: hover:bg-muted/50 cursor-pointer rounded-lg

Forms & Input

Multi-Step Forms

• Progress indicator at top: numbered steps with connecting line, current step highlighted
• One primary action per step ("Continue" / "Next Step") — right-aligned
• Back button: secondary style, left-aligned
• Validate each step before allowing progression
• Show summary/review step before final submission
• Animate step transitions: slide left/right with AnimatePresence

Search & Filters

• Search bar: prominent placement, w-full max-w-md with search icon left, clear button right
• Filter pattern: sidebar filters (checkboxes, range sliders) + active filter chips above results
• Instant filtering preferred — filter as user types (debounce 300ms)
• Show result count: "Showing 24 of 156 results"
• Empty search state: "No results for '[query]'. Try adjusting your filters."

Inline Editing

• Display mode: text looks like regular content
• Edit mode: click to transform into input field with save/cancel buttons
• Use autoFocus on the input, save on Enter, cancel on Escape
• Optimistic update: show new value immediately, revert on error

Feedback & States

Empty States

• Structure: illustration/icon (64-96px) → heading → description → primary action button
• Center in the available space: flex flex-col items-center justify-center py-16
• Message tone: helpful, not blaming ("No projects yet" not "You have no projects")
• Always provide a next action: "Create your first project" with a prominent button

Loading Skeletons

• Match the shape of the content they replace (skeleton cards, skeleton table rows, skeleton text)
• Use animate-pulse bg-muted rounded for skeleton elements
• Show 3-5 skeleton items (not 1, not 20)
• Never use spinning loaders for content loading — spinners only for actions (button submitting)

Error States

• Inline errors: red text below the input, icon left-aligned, specific message
• Page errors: centered card with error icon, friendly message, retry button, link to go back
• Toast errors: slide-in from top-right, auto-dismiss after 5s, include dismiss button
• Never show raw error messages, stack traces, or error codes to users

Success Confirmations

• Toast: slide-in from top-right via Framer Motion, green accent, auto-dismiss 3-4s
• Inline: checkmark icon + "Saved successfully" replacing the action button briefly
• Full-page: celebration moment for major completions (onboarding done, first project created)

Overlays & Modals

Dialog (Modal)

• Use for: confirmations, important choices that block other interaction
• Structure: title → description → content → footer with cancel + primary action buttons
• Backdrop: bg-black/50 backdrop-blur-sm — click to close
• Animate: scale 0.95→1 + opacity 0→1, duration 200ms
• Max width: max-w-md for confirmations, max-w-lg for forms, max-w-2xl for content

Sheet (Slide Panel)

• Use for: detail views, forms, settings that need more space than a dialog
• Slide from right (default), width: w-[400px] to w-[600px]
• Structure: header with title + close button → scrollable content → sticky footer with actions
• Animate: translateX 100%→0%, duration 300ms with spring easing

Command Palette

• Use for: power user navigation, quick actions, search across the app
• Trigger: Cmd+K / Ctrl+K
• shadcn Command component with search input, grouped results, keyboard navigation
• Show recent items, then search results grouped by category

Page Compositions

Dashboard Layout

┌─────────────────────────────────┐
│ Sidebar │ Header (breadcrumb + actions) │
│         │───────────────────────────────│
│ Nav     │ KPI Cards (4-col grid)        │
│ Items   │───────────────────────────────│
│         │ Chart      │ Activity Feed    │
│         │ (col-span-8)│ (col-span-4)    │
│         │───────────────────────────────│
│         │ Data Table (full width)        │
└─────────────────────────────────┘

Main content: grid grid-cols-12 gap-6 p-6

Settings Page

┌─────────────────────────────────┐
│ Header: Settings                 │
│─────────────────────────────────│
│ Tab Nav │ Form Section           │
│ Profile │ ┌─────────────────┐   │
│ Account │ │ Field + Label    │   │
│ Billing │ │ Field + Label    │   │
│ Team    │ │ [Save Changes]   │   │
│         │ └─────────────────┘   │
└─────────────────────────────────┘

Sidebar: w-48 with vertical nav. Content: max-w-2xl form sections.

Onboarding Wizard

┌─────────────────────────────────┐
│        Step 1 ─ 2 ─ 3 ─ 4      │
│ ┌─────────────────────────────┐ │
│ │    Centered Card             │ │
│ │    Step content              │ │
│ │                              │ │
│ │    [Back]        [Continue]  │ │
│ └─────────────────────────────┘ │
└─────────────────────────────────┘

Centered: flex items-center justify-center min-h-screen. Card: max-w-lg w-full.

List/Detail (Master-Detail)

┌─────────────────────────────────┐
│ Header + Search/Filters          │
│─────────────────────────────────│
│ List (1/3)   │ Detail (2/3)     │
│ ┌──────────┐ │ ┌─────────────┐ │
│ │ Item ●   │ │ │ Full detail  │ │
│ │ Item     │ │ │ of selected  │ │
│ │ Item     │ │ │ item         │ │
│ └──────────┘ │ └─────────────┘ │
└─────────────────────────────────┘

Split: grid grid-cols-3. List: col-span-1 border-r overflow-y-auto. Detail: col-span-2.