# orecus Component Registry > Documentation for LLMs and AI assistants > Homepage: https://orecus.io --- ## Overview orecus is a component registry built on top of shadcn/ui patterns. Components can be installed via the shadcn CLI with the registry URL. ### Installation ```bash npx shadcn@latest add "https://orecus.io/r/" ``` ### Skeleton Components Most components include a matching skeleton component for loading states: - **Server-side compatible**: Skeletons are pure server components (no 'use client') - **Same-API pattern**: Skeletons accept the same props as the real component - **Copy-paste workflow**: Copy your component usage, change the import to the skeleton - **Perfect layout matching**: Structural props (fields, columns, icons) determine skeleton layout **Example workflow:** ```tsx // In your page: // In your loading.tsx - same props work: ``` Skeleton imports follow the pattern: `import { ComponentSkeleton } from "@/components/ui/orecus.io/.../skeleton"` --- ## Components ### Utilities & Hooks - **Chart Utilities** (`chart-utils`) Shared helper functions for chart components, including CSS variable name sanitization. - **Color Utilities** (`color-utils`) Shared 20-color theme palette with gradient, glow, border, and text styles for consistent theming across components. - **useReducedMotion Hook** (`use-reduced-motion`) A React hook that detects the user's reduced motion preference using useSyncExternalStore for React 18+ concurrent mode safety. - **useWillChange Hook** (`use-will-change`) A React hook to manage will-change CSS property lifecycle. Applies will-change before animation starts and removes it after completion for optimal performance. - **Animation Constants** (`animation`) Centralized animation system with timing constants, easing functions, spring configs, CSS transitions, entry variants, stagger delays, and shared motion variants for consistent animations across components. - Dependencies: motion - **useTiltAnimation Hook** (`use-tilt-animation`) A React hook for 3D tilt and zoom hover effects on cards and other elements. Optimized for performance with hardware acceleration, RAF throttling, and reduced motion support. - Dependencies: motion - Registry dependencies: use-reduced-motion, use-will-change, animation - **useAnimatedNumber Hook** (`use-animated-number`) A React hook that animates numeric values from 0 to their target on mount. Parses prefixes/suffixes ($, %, commas) and preserves formatting during animation. Uses motion's animate() with reduced motion support. - Dependencies: motion - Registry dependencies: use-reduced-motion - **useLazyLoad Hook** (`use-lazy-load`) A minimal React hook for lazy loading content when it scrolls into view. Uses IntersectionObserver with sensible defaults for image and data preloading. ### Components - **Enhanced Button** (`enhanced-button`) An extended button component with loading states, icon support (left/right), glassmorphism, gradient, and solid color variants with glow and hover effects. Wraps shadcn/ui Button. - Registry dependencies: button, spinner, color-utils - **Loading Overlay** (`loading-overlay`) A loading overlay component with spinner and fade-in animation. Displays over content to indicate loading state. - **Progress** (`progress`) An extended progress bar component with gradient variants, theme colors, animated fills, shine effects, size options, and over-budget styling. Wraps shadcn/ui Progress. - Dependencies: motion - Registry dependencies: progress, color-utils - **Enhanced Empty State** (`enhanced-empty-state`) A beautiful, animated empty state component with floating icons, background glow effects, staggered animations, optional CTA button, and quick-start suggestion badges. Respects reduced-motion preferences. - Dependencies: motion, lucide-react - Registry dependencies: enhanced-button, badge, use-reduced-motion, color-utils ### Cards - **Category Card** (`category-card`) A card component with glassmorphism effects, gradient hover states, and motion animations. Perfect for showcasing categories, features, or navigation items. - Dependencies: motion - Registry dependencies: color-utils, card, stat-badge - **Card** (`card`) An extended Card component with glassmorphism variants (subtle, normal, strong), loading skeleton state, hover glow effects, accent bars, and customizable accent colors. Wraps shadcn/ui Card. - Dependencies: motion - Registry dependencies: card, skeleton, color-utils, use-tilt-animation, use-reduced-motion - **Badge Card** (`badge-card`) A card component with a gradient accent bar, header with icon/title/count, and a flex-wrap grid of badges. Uses solid gradient styling for the accent bar. - Registry dependencies: stat-badge, color-utils, card - **Entity Card** (`entity-card`) A versatile card component for displaying entity data with support for images, fields, metrics, progress bars, status badges, and tilt animations. Uses generic typing for type-safe entity rendering. - Dependencies: motion - Registry dependencies: progress, color-utils, use-tilt-animation - **Image Card** (`image-card`) An image-centric card component with overlay content. Supports 'overlay' variant (content centered on image) and 'fullHeight' variant (title at top, content at bottom). Includes configurable overlay styles (dark, light, gradient) and tilt animations. - Dependencies: motion - Registry dependencies: color-utils, use-reduced-motion, use-tilt-animation, entity-card ### Statistics - **Stat Card** (`stat-card`) A versatile statistics card with icon, title, main/secondary stats, metrics grid, and extensible footer slot. Includes loading skeleton states and compound components for custom layouts. - Dependencies: lucide-react, motion - Registry dependencies: skeleton, color-utils, card, header, use-reduced-motion, use-animated-number - **Stat Ring** (`stat-ring`) A circular progress ring component with gradient strokes, mount animations, glow effects, and optional end-cap markers. SVG-based with customizable size, thickness, and colors. - Dependencies: motion - Registry dependencies: skeleton, color-utils, card - **Stat Trend** (`stat-trend`) A compact stat card with embedded sparkline chart for visualizing trends over time. Includes optional trend indicator with direction. - Dependencies: lucide-react, motion - Registry dependencies: skeleton, sparkline, color-utils, card, use-reduced-motion - **Stat Comparison** (`stat-comparison`) A side-by-side comparison component for visualizing differences between two values with optional progress bar and change indicator. - Dependencies: lucide-react, motion - Registry dependencies: skeleton, color-utils, card, progress, use-reduced-motion, use-animated-number - **Stat List** (`stat-list`) A ranked/ordered list of statistics with optional progress bars, icons, and per-item colors. Perfect for leaderboards, top items, and category breakdowns. - Dependencies: lucide-react, motion - Registry dependencies: skeleton, color-utils, card, header, progress, use-reduced-motion - **Stat Delta** (`stat-delta`) A change-focused stat display with large directional arrow and color-coded indicators. Ideal for quick status checks and performance deltas. - Dependencies: lucide-react, motion - Registry dependencies: skeleton, color-utils, card, use-reduced-motion, use-animated-number - **Stat Badge** (`stat-badge`) A compact inline badge for embedding stats in text or headers. Features pulse indicator, icons, glass effects, accent bars, hover/click interactions, and multiple variants. - Dependencies: lucide-react - Registry dependencies: color-utils, skeleton - **Stat Bullet** (`stat-bullet`) A horizontal bullet chart with actual value bar, target marker, and qualitative range zones for KPI-to-target tracking. - Dependencies: motion - Registry dependencies: skeleton, color-utils, card, header, use-reduced-motion, use-animated-number - **Stat Gauge** (`stat-gauge`) A semi-circular arc gauge with gradient strokes, range zones, mount animations, and glow effects. SVG-based with customizable size, thickness, and colors. - Dependencies: motion - Registry dependencies: skeleton, color-utils, card, use-reduced-motion, use-animated-number ### Charts - **Chart** (`chart`) Beautiful, responsive charts built with Recharts v3. This component acts as the base primitive for all other charts. - Dependencies: recharts - Registry dependencies: card, header, loading-overlay - **Sparkline** (`sparkline`) A lightweight SVG sparkline component for visualizing data trends. Supports line, area, and bar variants with gradient and glow effects. - Dependencies: motion - Registry dependencies: skeleton, color-utils, use-reduced-motion - **Area Chart** (`area-chart`) An area chart component built using Recharts v3. Supports stacked areas, gradients, and custom tooltips. - Registry dependencies: chart, color-utils, chart-utils, card - **Line Chart** (`line-chart`) A line chart component built using Recharts v3. Supports multi-series, dot customization, curve types, and connectNulls. - Registry dependencies: chart, color-utils, chart-utils, card - **Bar Chart** (`bar-chart`) A bar chart component built using Recharts v3. Supports vertical/horizontal layout, stacked/grouped bars, and customizable styling. - Registry dependencies: chart, color-utils, chart-utils, card - **Pie Chart** (`pie-chart`) A pie/donut chart component built using Recharts v3. Supports donut variant with center labels, slice labels, and customizable styling. - Registry dependencies: chart, color-utils, chart-utils, card - **Radial Chart** (`radial-chart`) A radial/gauge chart component built using Recharts v3. Supports progress gauges, multi-value radial bars, and customizable angles. - Registry dependencies: chart, color-utils, chart-utils, card - **Combined Chart** (`combined-chart`) A combined bar + line chart component built using Recharts v3. Overlay bars and lines in a single chart for comparative analysis. - Registry dependencies: chart, color-utils, chart-utils, card - **Funnel Chart** (`funnel-chart`) A funnel chart component built using Recharts v3. Visualize stage-based conversion data with customizable colors, gradients, and glow effects. - Registry dependencies: chart, color-utils, chart-utils, card - **Sankey Chart** (`sankey-chart`) A Sankey diagram component built using Recharts v3. Visualize flow data between nodes with customizable links, gradients, and glow effects. - Registry dependencies: chart, color-utils, chart-utils, card - **Sunburst Chart** (`sunburst-chart`) A sunburst chart component built using Recharts v3. Visualize hierarchical data in concentric rings with customizable colors, gradients, and glow effects. - Registry dependencies: chart, color-utils, chart-utils, card - **Heatmap Chart** (`heatmap-chart`) A heatmap/matrix chart for visualizing value density across two dimensions. Built with custom SVG for activity grids, correlation matrices, and intensity maps. - Dependencies: motion - Registry dependencies: chart, color-utils, card - **Radar Chart** (`radar-chart`) A radar/spider chart component built using Recharts v3. Visualize multi-variable data across 3+ dimensions with customizable colors, gradients, glow effects, and interactive legend. - Registry dependencies: chart, color-utils, chart-utils, card - **Scatter Chart** (`scatter-chart`) A scatter/bubble chart component built using Recharts v3. Visualize two-variable correlation data with series-based API, bubble mode via zKey, customizable colors, gradients, glow effects, and interactive legend. - Registry dependencies: chart, color-utils, chart-utils, card ### Navigation - **Tabs** (`tabs`) Versatile tab component with glass styling, animated indicators, badge support, and compound component pattern for content panels. - Dependencies: motion - Registry dependencies: color-utils, badge, skeleton - **Breadcrumb** (`breadcrumb`) A breadcrumb navigation component with glass styling, multiple separator styles, size variants, and automatic truncation with dropdown. - Dependencies: lucide-react - Registry dependencies: color-utils, dropdown-menu - **Sidebar** (`sidebar`) A full-featured collapsible sidebar with compound components, mobile Sheet support, nested items, search filtering, badges, and multiple visual variants. - Dependencies: motion, lucide-react - Registry dependencies: sheet, input-group, button, separator, enhanced-button, card, color-utils ### Layout - **Header** (`header`) A flexible section header component with icon, title, description, size variants, action slots, and configurable heading level for accessibility. Includes staggered reveal animation, icon hover effects, loading skeleton state, and compound components for custom layouts. - Dependencies: motion - Registry dependencies: skeleton - **Image Gallery** (`image-gallery`) A flexible image gallery with grid/scroll layouts, lightbox modal, hover effects, and compound component pattern for full customization. - Dependencies: motion, lucide-react - Registry dependencies: card, header, enhanced-button, enhanced-empty-state, use-reduced-motion, skeleton - **Info Bar** (`info-bar`) An announcement/alert bar component with glass styling, icons, actions, and dismissible functionality. Supports multiple variants, accent bars, and CSS enter animations. - Dependencies: lucide-react - Registry dependencies: color-utils, button - **Entity Grid** (`entity-grid`) A composable grid component for displaying entity collections. Uses compound components (EntityGrid.Header, EntityGrid.Content, EntityGrid.Empty, EntityGrid.Error, EntityGrid.Stats, EntityGrid.Filters) for flexible layouts. Supports EntityCard mode, ImageCard mode, or custom render functions. Two loading variants: skeleton or blurred overlay. Flexible ID handling with keyExtractor prop. Built-in SectionHeader and EnhancedEmptyState integration. - Dependencies: motion, lucide-react - Registry dependencies: entity-card, image-card, header, enhanced-empty-state, use-reduced-motion, use-tilt-animation, enhanced-button, loading-overlay, popover - **Timeline** (`timeline`) A compound component timeline with center/left/right alignment, motion animations, and server-compatible skeleton. Features iconPosition prop to show icons on timeline dots or in cards. Uses Timeline.Item, Timeline.Card, Timeline.Header, and Timeline.Dot sub-components. - Dependencies: motion, lucide-react - Registry dependencies: color-utils, card, header - **Entity Table** (`entity-table`) A composable table component for displaying tabular data. Uses compound components (EntityTable.Header, EntityTable.Toolbar, EntityTable.Empty, EntityTable.Error, EntityTable.Pagination) for flexible layouts. Supports sorting, searching, row selection, bulk actions, column visibility, stagger animations, glass effect styling (type/invert), row density (gap), and both load-more and page-based pagination. Two loading variants: skeleton or blurred overlay. Flexible ID handling with keyExtractor prop. No tanstack/react-table dependency. - Dependencies: motion, lucide-react - Registry dependencies: header, enhanced-empty-state, enhanced-button, use-reduced-motion, loading-overlay, color-utils, checkbox, dropdown-menu, tooltip, skeleton, input, popover - **Entity Hero** (`entity-hero`) A hero section component for displaying entity details with full-width image background, glassmorphism panels, and animated content. Supports ViewTransition for smooth page transitions. - Dependencies: motion - Registry dependencies: skeleton, use-reduced-motion, color-utils ### Blocks - **Dashboard** (`dashboard`) A composable dashboard block with stats grid, charts section, and data table. Perfect for admin dashboards and analytics overviews. - Registry dependencies: header, stat-card, chart, card, entity-table - **Entity Page** (`entity-page`) A full page layout composition combining breadcrumb navigation, entity hero, and content area with single or split layout modes. - Dependencies: motion - Registry dependencies: entity-hero, breadcrumb, use-reduced-motion, color-utils - **Analytics** (`analytics`) A data-intensive analytics block with KPI deltas, comparison charts, breakdowns, and trend indicators. Ideal for performance dashboards. - Registry dependencies: header, stat-delta, stat-trend, stat-list, chart, card - **App Shell** (`app-shell`) A composable application shell layout coordinating Sidebar, Header, Main content, and Footer areas with synchronized entry animations and fixed/floating variants. - Dependencies: motion - Registry dependencies: sidebar, color-utils --- ## Component Details ### Utilities & Hooks #### Chart Utilities **Name:** `chart-utils` Shared helper functions for chart components, including CSS variable name sanitization. **Usage:** ```tsx import { toCssVarName } from "@/components/ui/orecus.io/lib/chart-utils"; // Convert category names to CSS-safe variable names toCssVarName("Product Sales"); // → "Product-Sales" ``` --- #### Color Utilities **Name:** `color-utils` Shared 20-color theme palette with gradient, glow, border, and text styles for consistent theming across components. **Usage:** ```tsx import { type ThemeColor, colorStyles, getColorStyle } from "@/components/ui/orecus.io/lib/color-utils"; // Use ThemeColor for type-safe color props interface MyComponentProps { color?: ThemeColor; // primary, secondary, teal, purple, etc. } // Get styles for a color const style = getColorStyle("purple"); // style.gradient → "from-purple-500/80 to-purple-400" // style.glow → "shadow-purple-500/30" // style.border → "border-purple-500/50" // style.text → "text-white" // Apply to an element
Gradient background with matching text
``` --- #### useReducedMotion Hook **Name:** `use-reduced-motion` A React hook that detects the user's reduced motion preference using useSyncExternalStore for React 18+ concurrent mode safety. **Usage:** ```tsx import { useReducedMotion } from "@/components/ui/orecus.io/lib/use-reduced-motion"; // Returns true if user prefers reduced motion const prefersReducedMotion = useReducedMotion(); // Use with motion components Content ``` --- #### useWillChange Hook **Name:** `use-will-change` A React hook to manage will-change CSS property lifecycle. Applies will-change before animation starts and removes it after completion for optimal performance. **Usage:** ```tsx import { useWillChange } from "@/components/ui/orecus.io/lib/use-will-change"; const [isAnimating, setIsAnimating] = useState(false); const elementRef = useRef(null); useWillChange(elementRef, 'transform', isAnimating); return
Content
; ``` --- #### Animation Constants **Name:** `animation` Centralized animation system with timing constants, easing functions, spring configs, CSS transitions, entry variants, stagger delays, and shared motion variants for consistent animations across components. **Usage:** ```tsx import { DURATIONS, EASE, SPRING, CSS_TRANSITIONS, CSS_HOVER, ENTRY_VARIANTS, STAGGER_DELAYS, SHARED_VARIANTS, ANIMATION_PROPS, } from "@/components/ui/orecus.io/lib/animation"; // Use CSS classes for simple hover effects
// Use motion variants for complex animations // Use animation props for inline animations ``` --- #### useTiltAnimation Hook **Name:** `use-tilt-animation` A React hook for 3D tilt and zoom hover effects on cards and other elements. Optimized for performance with hardware acceleration, RAF throttling, and reduced motion support. **Usage:** ```tsx import { useTiltAnimation } from "@/components/ui/orecus.io/lib/use-tilt-animation"; const { motionProps, tiltRef } = useTiltAnimation({ style: "tilt", tilt: { max: 10 } }); return ( Card content ); ``` --- #### useAnimatedNumber Hook **Name:** `use-animated-number` A React hook that animates numeric values from 0 to their target on mount. Parses prefixes/suffixes ($, %, commas) and preserves formatting during animation. Uses motion's animate() with reduced motion support. **Usage:** ```tsx import { useAnimatedNumber } from "@/components/ui/orecus.io/lib/use-animated-number"; // Returns a ref to attach to the display element const { ref } = useAnimatedNumber("$48,352", { duration: 0.8 }); return $48,352; ``` --- #### useLazyLoad Hook **Name:** `use-lazy-load` A minimal React hook for lazy loading content when it scrolls into view. Uses IntersectionObserver with sensible defaults for image and data preloading. **Usage:** ```tsx import { useLazyLoad } from "@/components/ui/orecus.io/lib/use-lazy-load"; // Basic usage for lazy loading images function LazyImage({ src, alt }: { src: string; alt: string }) { const { ref, hasLoaded } = useLazyLoad({ rootMargin: "100px" }); return (
{hasLoaded ? {alt} : }
); } // Works great with data fetching const { ref, hasLoaded } = useLazyLoad(); const { data } = useSWR(hasLoaded ? '/api/data' : null, fetcher); ``` --- ### Components #### Enhanced Button **Name:** `enhanced-button` An extended button component with loading states, icon support (left/right), glassmorphism, gradient, and solid color variants with glow and hover effects. Wraps shadcn/ui Button. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `loading` | `boolean` | `false` | Shows spinner and disables button when true | | `leftIcon` | `ReactNode` | `-` | Icon to display before children (replaced by spinner when loading) | | `rightIcon` | `ReactNode` | `-` | Icon to display after children | | `variant` | `'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link' | 'glass' | 'gradient' | 'color'` | `'default'` | Button variant - 'glass' for glassmorphism, 'gradient' for colored gradient background, 'color' for flat solid color background | | `color` | `ThemeColor` | `'primary'` | Color for gradient and color variants (primary, secondary, green, amber, red, blue, purple, pink, cyan, teal, orange, indigo, emerald, violet, rose, slate, gray, zinc, neutral, stone) | | `glow` | `boolean` | `false` | Always-on glow effect around the button (for CTA buttons). Works with gradient and color variants. | | `hoverEffect` | `'none' | 'scale' | 'glow' | 'scale-glow'` | `'none'` | Hover animation - 'scale' for size change, 'glow' for shadow, 'scale-glow' for both | | `clickEffect` | `'none' | 'scale'` | `'none'` | Click animation - 'scale' for scale-down feedback on click/active | | `className` | `string` | `-` | Additional CSS classes for the button | --- #### Loading Overlay **Name:** `loading-overlay` A loading overlay component with spinner and fade-in animation. Displays over content to indicate loading state. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `loading` | `boolean` | `false` | Whether the loading overlay is visible | | `text` | `string` | `"Loading..."` | Text to display below the spinner | | `className` | `string` | `-` | Additional CSS classes | --- #### Progress **Name:** `progress` An extended progress bar component with gradient variants, theme colors, animated fills, shine effects, size options, and over-budget styling. Wraps shadcn/ui Progress. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `value` | `number` | `-` | Current progress value (0-100) | | `variant` | `'default' | 'gradient'` | `'default'` | Style variant - 'gradient' for colored gradient fill | | `color` | `ThemeColor` | `'primary'` | Theme color for the gradient variant (primary, blue, green, purple, etc.) | | `size` | `'sm' | 'md' | 'lg'` | `'md'` | Height size of the progress bar | | `animated` | `boolean` | `false` | Animate the progress fill on mount | | `shine` | `boolean` | `false` | Add a shine effect animation to the progress bar | | `showOverBudget` | `boolean` | `false` | Apply destructive styling when value >= 100 | | `className` | `string` | `-` | Additional CSS classes for the progress bar | --- #### Enhanced Empty State **Name:** `enhanced-empty-state` A beautiful, animated empty state component with floating icons, background glow effects, staggered animations, optional CTA button, and quick-start suggestion badges. Respects reduced-motion preferences. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `title` (required) | `string` | `-` | Main title text | | `description` | `string` | `-` | Optional description text below the title | | `icon` | `LucideIcon` | `-` | Main central icon displayed in the animated composition | | `floatingIcons` | `FloatingIconConfig[]` | `-` | Array of floating icons around the main icon with position, color, and icon properties | | `cta` | `CTAConfig` | `-` | Optional CTA button configuration with label, onClick, icon, variant, size, and disabled properties | | `suggestions` | `SuggestionConfig[]` | `-` | Optional quick-start suggestions displayed as clickable badges | | `suggestionsLabel` | `string` | `-` | Optional label for suggestions section | | `className` | `string` | `-` | Additional CSS classes for the container | --- ### Cards #### Category Card **Name:** `category-card` A card component with glassmorphism effects, gradient hover states, and motion animations. Perfect for showcasing categories, features, or navigation items. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `title` (required) | `string` | `-` | Card title | | `description` (required) | `string` | `-` | Card description | | `onClick` | `() => void` | `-` | Click handler for card interaction | | `icon` (required) | `string` | `-` | Emoji or icon | | `color` | `ThemeColor` | `'primary'` | Theme color for gradient and border styling (primary, secondary, green, amber, red, blue, purple, pink, cyan, teal, orange, indigo, emerald, violet, rose, slate) | | `tags` (required) | `string[]` | `-` | Array of tag labels | | `animationDelay` | `number` | `0` | Animation delay for staggered entrance | | `disabled` | `boolean` | `false` | Whether the card is disabled (shows "Coming Soon" badge) | | `clickEffect` | `'none' | 'scale'` | `'none'` | Click animation - 'scale' for scale-down feedback on click/active | | `className` | `string` | `-` | Additional CSS classes for the outer wrapper | | `cardProps` | `Omit` | `-` | Additional props to pass to the underlying Card component | --- #### Card **Name:** `card` An extended Card component with glassmorphism variants (subtle, normal, strong), loading skeleton state, hover glow effects, accent bars, and customizable accent colors. Wraps shadcn/ui Card. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `type` | `'normal' | 'subtle' | 'strong' | 'solid' | 'none'` | `'none'` | Card style variant for different glass effects | | `invert` | `boolean` | `false` | Invert glass overlay approach (light-on-light, dark-on-dark) | | `shadow` | `'none' | 'sm' | 'default' | 'lg' | 'auto'` | `'auto'` | Shadow style | | `loading` | `boolean` | `false` | Shows skeleton loading state when true | | `border` | `boolean` | `true` | Show border around card | | `radius` | `'none' | 'sm' | 'default' | 'lg' | 'xl' | '2xl'` | `'default'` | Border radius size | | `hoverEffect` | `'none' | 'lift' | 'scale' | 'tilt'` | `'none'` | Hover effect style - 'lift' for translate up, 'scale' for size change, 'tilt' for 3D mouse-following tilt | | `tiltConfig` | `TiltConfig` | `-` | Configuration for tilt animation (max angle, perspective, scale, speed). Only used with tilt effects. | | `clickEffect` | `'none' | 'scale'` | `'none'` | Click effect style - 'scale' for scale-down feedback on click/active | | `hoverBorder` | `boolean` | `false` | Whether border color animates on hover using accentColor | | `hoverGlow` | `boolean` | `false` | Whether to show gradient glow effect behind card on hover | | `accentBar` | `'none' | 'top' | 'bottom'` | `'none'` | Gradient accent bar position | | `accentBarVariant` | `'fade' | 'solid'` | `'fade'` | Accent bar gradient style: 'fade' (center-out via-*) or 'solid' (full gradient) | | `accentColor` | `ThemeColor` | `'primary'` | Predefined accent color (primary, secondary, green, amber, red, blue, purple, pink, cyan, teal, orange, indigo, emerald, violet, rose, slate) | | `accentBarOnHover` | `boolean` | `false` | Whether accent bar appears only on hover | | `animationPreset` | `'none' | 'fade' | 'slide-up' | 'slide-down' | 'scale' | 'fade-slide' | 'slide-up-subtle'` | `'none'` | Entry animation preset | | `animationDelay` | `number` | `0` | Additional delay for entry animation in seconds | | `disableAnimations` | `boolean` | `false` | If true, card will not apply its own entry/exit animations. Useful when parent (e.g., EntityGrid) handles animations | | `exitAnimation` | `boolean` | `false` | If true, enables exit animations. Requires AnimatePresence in the parent component | | `animationDuration` | `number` | `-` | Custom duration for entry/exit animations in seconds. Overrides preset default | | `className` | `string` | `-` | Additional CSS classes for the card | --- #### Badge Card **Name:** `badge-card` A card component with a gradient accent bar, header with icon/title/count, and a flex-wrap grid of badges. Uses solid gradient styling for the accent bar. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `title` (required) | `string` | `-` | Title/name displayed in the header | | `icon` | `ReactNode` | `-` | Icon or emoji displayed before the title | | `badges` (required) | `string[]` | `-` | Array of badge labels to display | | `color` | `ThemeColor` | `'primary'` | Theme color for the accent bar gradient (primary, secondary, green, amber, etc.) | | `animationDelay` | `number` | `0` | Animation delay for staggered entrance animations | | `className` | `string` | `-` | Additional CSS classes for the card | | `badgeClassName` | `string` | `-` | Additional CSS classes for badge items | | `badgeProps` | `Omit` | `-` | Props to pass to each StatBadge component (e.g., variant, size, type, accentBar) | | `cardProps` | `Omit` | `-` | Additional props to pass to the underlying Card component (e.g., animationPreset, hoverEffect, etc.) | --- #### Entity Card **Name:** `entity-card` A versatile card component for displaying entity data with support for images, fields, metrics, progress bars, status badges, and tilt animations. Uses generic typing for type-safe entity rendering. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `entity` (required) | `T extends BaseEntity` | `-` | The entity object to display in the card | | `title` (required) | `CardTitle` | `-` | Title configuration with key, render function, and left/right content slots | | `image` | `CardImage` | `-` | Image configuration with src, alt, aspectRatio, objectFit | | `ImageComponent` | `React.ElementType` | `'img'` | Image component to use (e.g., next/image for Next.js) | | `fields` | `CardField[]` | `-` | Array of field configurations to display | | `metrics` | `MetricField[]` | `-` | Metrics displayed in a 2-column grid in the card body | | `footerMetrics` | `MetricField[]` | `-` | Metrics displayed in the footer section | | `progress` | `ProgressField` | `-` | Progress bar configuration with value, label, placement (top/bottom/footer) | | `status` | `StatusField` | `-` | Status badge displayed on the image with value and variant | | `hoverEffect` | `MaybeEntityValue` | `'none'` | Hover effect style. Supports static value or entity-derived function. | | `tiltConfig` | `TiltConfig` | `-` | Configuration for tilt animation (max angle, perspective, scale, speed). Only used with tilt effects. | | `hoverBorder` | `MaybeEntityValue` | `false` | Whether border color animates on hover. Supports static value or entity-derived function. | | `hoverGlow` | `MaybeEntityValue` | `false` | Whether to show gradient glow effect on hover. Supports static value or entity-derived function. | | `onClick` | `(entity: T) => void` | `-` | Click handler - makes card interactive with hover effects | | `type` | `MaybeEntityValue` | `'normal'` | Card glass effect variant. Supports static value or entity-derived function. | | `invert` | `MaybeEntityValue` | `false` | Invert glass overlay approach. Supports static value or entity-derived function. | | `accentBar` | `MaybeEntityValue` | `'none'` | Gradient accent bar position. Supports static value or entity-derived function. | | `accentBarVariant` | `MaybeEntityValue` | `'fade'` | Accent bar gradient style. Supports static value or entity-derived function. | | `accentColor` | `MaybeEntityValue` | `'primary'` | Predefined accent color for accent bar. Supports static value or entity-derived function for dynamic coloring per entity. | | `accentBarOnHover` | `MaybeEntityValue` | `false` | Whether accent bar appears only on hover. Supports static value or entity-derived function. | | `className` | `string` | `-` | Additional CSS classes for the card | | `loading` | `boolean` | `false` | Shows skeleton loading state when true | | `bento` | `BentoConfig` | `-` | Bento grid configuration. When provided, card uses h-full and flex layout to fill grid cells. Supports optional minHeight class override. | --- #### Image Card **Name:** `image-card` An image-centric card component with overlay content. Supports 'overlay' variant (content centered on image) and 'fullHeight' variant (title at top, content at bottom). Includes configurable overlay styles (dark, light, gradient) and tilt animations. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `entity` (required) | `T extends BaseEntity` | `-` | The entity object to display in the card | | `title` (required) | `CardTitle` | `-` | Title configuration with key, render function, and left/right content | | `image` (required) | `CardImage` | `-` | Required image configuration with src, alt, objectFit | | `ImageComponent` | `React.ElementType` | `'img'` | Image component to use (e.g., next/image) | | `variant` | `'overlay' | 'fullHeight'` | `'overlay'` | Card layout variant | | `overlayStyle` | `'dark' | 'light' | 'gradient'` | `'dark'` | Backdrop overlay style | | `fields` | `CardField[]` | `-` | Array of field configurations to display | | `footer` | `ReactNode | ((entity: T) => ReactNode)` | `-` | Optional footer content | | `height` | `number` | `300` | Card height for fullHeight variant | | `hoverEffect` | `MaybeEntityValue` | `'none'` | Hover effect style. Supports static value or entity-derived function. | | `tiltConfig` | `TiltConfig` | `-` | Configuration for tilt animation (max angle, perspective, scale, speed). Only used with tilt effects. | | `hoverBorder` | `MaybeEntityValue` | `false` | Whether border color animates on hover. Supports static value or entity-derived function. | | `hoverGlow` | `MaybeEntityValue` | `false` | Whether to show gradient glow effect on hover. Supports static value or entity-derived function. | | `onClick` | `(entity: T) => void` | `-` | Click handler - makes card interactive | | `className` | `string` | `-` | Additional CSS classes | | `type` | `MaybeEntityValue` | `'none'` | Card glass effect variant. Supports static value or entity-derived function. | | `accentBar` | `MaybeEntityValue` | `'none'` | Gradient accent bar position. Supports static value or entity-derived function. | | `accentBarVariant` | `MaybeEntityValue` | `'fade'` | Accent bar gradient style. Supports static value or entity-derived function. | | `accentColor` | `MaybeEntityValue` | `'primary'` | Predefined accent color for accent bar. Supports static value or entity-derived function for dynamic coloring per entity. | | `accentBarOnHover` | `MaybeEntityValue` | `false` | Whether accent bar appears only on hover. Supports static value or entity-derived function. | | `loading` | `boolean` | `false` | Shows skeleton loading state when true | | `bento` | `BentoConfig` | `-` | Bento grid configuration. When provided, card uses h-full to fill grid cells. Supports optional minHeight class override. | --- ### Statistics #### Stat Card **Name:** `stat-card` A versatile statistics card with icon, title, main/secondary stats, metrics grid, and extensible footer slot. Includes loading skeleton states and compound components for custom layouts. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `title` (required) | `string` | `-` | Title text for the card header | | `icon` (required) | `LucideIcon` | `-` | Icon component to display in the header | | `description` | `ReactNode` | `-` | Description text below the title | | `mainStat` (required) | `StatValue` | `-` | Main statistic with value, label, and optional color | | `secondaryStat` | `StatValue` | `-` | Optional secondary statistic displayed on the right | | `metrics` | `StatMetric[]` | `-` | Array of metrics with icon, value, label, and color | | `metricsColumns` | `number` | `3` | Number of columns for the metrics grid (1-4) | | `action` | `ReactNode` | `-` | Optional action content in the header (e.g., button) | | `footer` | `ReactNode` | `-` | Optional footer content (e.g., sparkline, progress bar) | | `cardProps` | `CardProps` | `-` | Props to pass to the Card wrapper (type, hoverEffect, accentColor, etc.) | | `animated` | `boolean` | `true` | Whether to animate elements on mount | | `animateValue` | `boolean` | `true` | Whether to animate numeric values with a counting effect | | `compact` | `boolean` | `false` | Compact layout variant | | `loading` | `boolean` | `false` | Shows skeleton loading state when true | | `className` | `string` | `-` | Additional CSS classes for the card | --- #### Stat Ring **Name:** `stat-ring` A circular progress ring component with gradient strokes, mount animations, glow effects, and optional end-cap markers. SVG-based with customizable size, thickness, and colors. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `value` (required) | `number` | `-` | Current value (0 to max) | | `max` | `number` | `100` | Maximum value | | `label` (required) | `string` | `-` | Label text below the ring | | `color` | `ThemeColor` | `'primary'` | Ring color | | `size` | `'sm' | 'md' | 'lg'` | `'md'` | Size variant | | `thickness` | `number` | `-` | Custom stroke width (overrides size default) | | `showValue` | `boolean` | `true` | Show value in center | | `formatValue` | `(value: number, max: number) => string` | `-` | Custom format function for displayed value | | `description` | `ReactNode` | `-` | Additional content below the ring | | `loading` | `boolean` | `false` | Shows skeleton loading state | | `cardProps` | `CardProps` | `-` | Props to pass to the Card wrapper | | `className` | `string` | `-` | Additional CSS classes | | `variant` | `'default' | 'gradient'` | `'default'` | Ring style variant - 'gradient' uses SVG gradient for the stroke | | `animated` | `boolean` | `false` | Animate the ring fill on mount | | `glow` | `boolean` | `false` | Add colored glow/shadow effect behind the ring | | `trackVariant` | `'subtle' | 'dashed'` | `'subtle'` | Background track styling | | `icon` | `ReactNode` | `-` | Icon to show in center instead of value | | `showMarker` | `boolean` | `false` | Show a marker dot at the ring progress tip | | `markerGlow` | `boolean` | `false` | Add animated pulse glow to the marker | | `thresholds` | `{ value: number; color: ThemeColor; label?: string }[]` | `-` | Threshold breakpoints that change ring color based on value ranges | --- #### Stat Trend **Name:** `stat-trend` A compact stat card with embedded sparkline chart for visualizing trends over time. Includes optional trend indicator with direction. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `value` (required) | `string | number` | `-` | Main value to display | | `label` (required) | `string` | `-` | Label for the stat | | `data` (required) | `number[] | SparklineSeries[]` | `-` | Sparkline data points (single array or multi-series objects with name, data, and optional color) | | `trend` | `{ value: string; direction: 'up' | 'down' | 'neutral'; color?: ThemeColor }` | `-` | Optional trend indicator | | `color` | `ThemeColor` | `'primary'` | Sparkline color | | `showFill` | `boolean` | `true` | Show area fill under sparkline | | `sparklineWidth` | `number` | `150` | Width of the sparkline in pixels | | `sparklineHeight` | `number` | `48` | Height of the sparkline in pixels | | `sparklineType` | `'line' | 'area' | 'bar'` | `-` | Sparkline type (line, area, or bar) | | `curved` | `boolean` | `false` | Whether to use smooth curves | | `animated` | `boolean` | `true` | Whether to animate the sparkline on mount | | `animateText` | `boolean` | `true` | Whether to animate text elements (label, value, trend) | | `showLegend` | `boolean` | `false` | Show legend below sparkline for multi-series data | | `loading` | `boolean` | `false` | Shows skeleton loading state | | `cardProps` | `CardProps` | `-` | Props to pass to the Card wrapper | | `className` | `string` | `-` | Additional CSS classes | --- #### Stat Comparison **Name:** `stat-comparison` A side-by-side comparison component for visualizing differences between two values with optional progress bar and change indicator. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `title` (required) | `string` | `-` | Title for the comparison | | `primary` (required) | `{ value: number | string; label: string }` | `-` | Primary/current value | | `secondary` (required) | `{ value: number | string; label: string }` | `-` | Secondary/comparison value | | `difference` | `{ value: string; direction: 'up' | 'down' | 'neutral'; color?: ThemeColor }` | `-` | Difference indicator | | `showBar` | `boolean` | `true` | Show visual comparison bar | | `barColor` | `ThemeColor` | `'primary'` | Color for the comparison bar | | `animated` | `boolean` | `true` | Whether to animate elements on mount | | `animateValue` | `boolean` | `true` | Whether to animate numeric values with a counting effect | | `loading` | `boolean` | `false` | Shows skeleton loading state | | `cardProps` | `CardProps` | `-` | Props to pass to the Card wrapper | | `className` | `string` | `-` | Additional CSS classes | --- #### Stat List **Name:** `stat-list` A ranked/ordered list of statistics with optional progress bars, icons, and per-item colors. Perfect for leaderboards, top items, and category breakdowns. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `title` | `string` | `-` | Optional title for the list | | `description` | `ReactNode` | `-` | Optional description for the list | | `items` (required) | `StatListItem[]` | `-` | Array of items with label, value, optional icon and color | | `showRank` | `boolean` | `false` | Show rank numbers | | `showBar` | `boolean` | `true` | Show progress bars | | `maxValue` | `number` | `-` | Maximum value for percentage calculation (auto-detected if not set) | | `color` | `ThemeColor` | `'primary'` | Default color for bars | | `action` | `ReactNode` | `-` | Optional action in the header | | `animated` | `boolean` | `true` | Whether to animate the list items | | `loading` | `boolean` | `false` | Shows skeleton loading state | | `cardProps` | `CardProps` | `-` | Props to pass to the Card wrapper | | `className` | `string` | `-` | Additional CSS classes | --- #### Stat Delta **Name:** `stat-delta` A change-focused stat display with large directional arrow and color-coded indicators. Ideal for quick status checks and performance deltas. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `value` (required) | `string` | `-` | Change value (e.g., '+23.4%', '-$1,200') | | `label` (required) | `string` | `-` | Label for the change | | `direction` (required) | `'up' | 'down' | 'neutral'` | `-` | Direction of change | | `description` | `ReactNode` | `-` | Optional description text | | `color` | `ThemeColor` | `-` | Color override (auto-set by direction if not specified) | | `iconSize` | `'sm' | 'md' | 'lg'` | `'md'` | Size of the arrow icon | | `animated` | `boolean` | `true` | Whether to animate text elements on mount | | `animateValue` | `boolean` | `true` | Whether to animate numeric values with a counting effect | | `loading` | `boolean` | `false` | Shows skeleton loading state | | `cardProps` | `CardProps` | `-` | Props to pass to the Card wrapper | | `className` | `string` | `-` | Additional CSS classes | --- #### Stat Badge **Name:** `stat-badge` A compact inline badge for embedding stats in text or headers. Features pulse indicator, icons, glass effects, accent bars, hover/click interactions, and multiple variants. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `value` (required) | `string | number` | `-` | Value to display | | `label` | `string` | `-` | Optional label | | `icon` | `LucideIcon` | `-` | Optional icon | | `color` | `ThemeColor` | `'primary'` | Badge color - affects text/icon colors and accent bar | | `variant` | `'default' | 'outline' | 'ghost'` | `'default'` | Visual variant | | `size` | `'sm' | 'md'` | `'md'` | Badge size | | `pulse` | `boolean` | `false` | Show pulsing dot indicator | | `type` | `'normal' | 'subtle' | 'strong' | 'solid' | 'none'` | `'none'` | Glass effect style. When not 'none', replaces color-based background with glass | | `invert` | `boolean` | `false` | Invert glass overlay approach (white-on-light, dark-on-dark) | | `accentBar` | `'none' | 'top' | 'bottom'` | `'none'` | Gradient accent bar position | | `accentBarVariant` | `'fade' | 'solid'` | `'fade'` | Accent bar gradient style | | `accentColor` | `ThemeColor` | `-` | Color for accent bar (defaults to color prop) | | `accentBarOnHover` | `boolean` | `false` | Whether accent bar appears only on hover | | `hoverEffect` | `'none' | 'lift' | 'scale'` | `'none'` | Hover effect style | | `hoverBorder` | `boolean` | `false` | Whether border color animates on hover using accentColor | | `onClick` | `() => void` | `-` | Click handler - makes badge interactive | | `clickEffect` | `'none' | 'scale'` | `'none'` | Click effect style | | `shadow` | `'none' | 'sm' | 'default' | 'lg'` | `'none'` | Shadow style | | `radius` | `'none' | 'sm' | 'default' | 'lg' | 'full'` | `'full'` | Border radius | | `loading` | `boolean` | `false` | Shows skeleton loading state | | `className` | `string` | `-` | Additional CSS classes | --- #### Stat Bullet **Name:** `stat-bullet` A horizontal bullet chart with actual value bar, target marker, and qualitative range zones for KPI-to-target tracking. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `value` (required) | `number` | `-` | Current/actual value | | `max` | `number` | `100` | Scale maximum | | `label` (required) | `string` | `-` | Label text | | `color` | `ThemeColor` | `'primary'` | Bar color | | `target` | `number` | `-` | Target marker position | | `targetLabel` | `string` | `-` | Label for target (e.g., 'Goal') | | `ranges` | `{ value: number; color: ThemeColor; label?: string }[]` | `-` | Background qualitative range zones sorted ascending | | `showValue` | `boolean` | `true` | Show value text | | `formatValue` | `(value: number, max: number) => string` | `-` | Custom format function for displayed value | | `description` | `ReactNode` | `-` | Additional description text | | `size` | `'sm' | 'md' | 'lg'` | `'md'` | Bar height preset | | `variant` | `'default' | 'gradient'` | `'default'` | Bar fill style | | `animated` | `boolean` | `false` | Animate bar width on mount | | `glow` | `boolean` | `false` | Glow effect on feature bar | | `animateValue` | `boolean` | `true` | Number counting animation | | `loading` | `boolean` | `false` | Shows skeleton loading state | | `cardProps` | `CardProps` | `-` | Props to pass to the Card wrapper | | `className` | `string` | `-` | Additional CSS classes | --- #### Stat Gauge **Name:** `stat-gauge` A semi-circular arc gauge with gradient strokes, range zones, mount animations, and glow effects. SVG-based with customizable size, thickness, and colors. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `value` (required) | `number` | `-` | Current value (0 to max) | | `max` | `number` | `100` | Maximum value | | `label` (required) | `string` | `-` | Label text below the gauge | | `color` | `ThemeColor` | `'primary'` | Gauge color | | `ranges` | `{ value: number; color: ThemeColor; label?: string }[]` | `-` | Background qualitative range zones sorted ascending. Auto-derives progress color. | | `showValue` | `boolean` | `true` | Show value in the gauge center | | `formatValue` | `(value: number, max: number) => string` | `-` | Custom format function for displayed value | | `description` | `ReactNode` | `-` | Additional description text | | `size` | `'sm' | 'md' | 'lg'` | `'md'` | Size variant | | `thickness` | `number` | `-` | Custom stroke width (overrides size default) | | `variant` | `'default' | 'gradient'` | `'default'` | Gauge fill style | | `animated` | `boolean` | `false` | Animate gauge fill on mount | | `glow` | `boolean` | `false` | Glow effect on gauge arc | | `animateValue` | `boolean` | `true` | Number counting animation | | `icon` | `ReactNode` | `-` | Icon to show instead of value | | `showMarker` | `boolean` | `false` | Show marker dot at progress tip | | `markerGlow` | `boolean` | `false` | Add animated pulse glow to the marker | | `loading` | `boolean` | `false` | Shows skeleton loading state | | `cardProps` | `CardProps` | `-` | Props to pass to the Card wrapper | | `className` | `string` | `-` | Additional CSS classes | --- ### Charts #### Chart **Name:** `chart` Beautiful, responsive charts built with Recharts v3. This component acts as the base primitive for all other charts. --- #### Sparkline **Name:** `sparkline` A lightweight SVG sparkline component for visualizing data trends. Supports line, area, and bar variants with gradient and glow effects. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `data` (required) | `number[] | SparklineSeries[]` | `-` | Array of data points (or multi-series objects with name, data, and optional color) | | `type` | `'line' | 'area' | 'bar'` | `'line'` | Visual style of the sparkline | | `color` | `ThemeColor` | `'primary'` | Theme color for the chart | | `width` | `number` | `100` | Width in pixels | | `height` | `number` | `40` | Height in pixels | | `strokeWidth` | `number` | `2` | Line thickness in pixels (line/area types) | | `curved` | `boolean` | `true` | Whether to use smooth curves (line/area types) | | `showEndDot` | `boolean` | `true` | Whether to highlight the last data point | | `showFill` | `boolean` | `true` | Whether to fill the area under the line (area type) | | `barGap` | `number` | `2` | Gap between bars in pixels (bar type) | | `barRadius` | `number` | `2` | Corner radius for bars in pixels (bar type) | | `variant` | `'default' | 'gradient'` | `'gradient'` | Color style - 'gradient' uses soft SVG gradients | | `glow` | `boolean` | `true` | Add colored glow/blur effect (works best with gradient variant) | | `fullWidth` | `boolean` | `false` | Whether to fill the available width of the container | | `showTooltip` | `boolean` | `false` | Show tooltip with data value on hover | | `valueFormatter` | `(value: number) => string` | `-` | Formatter for tooltip values | | `animated` | `boolean` | `false` | Whether to animate the sparkline on mount | | `loading` | `boolean` | `false` | Shows skeleton loading state | | `className` | `string` | `-` | Additional CSS classes | | `referenceLines` | `SparklineReferenceLine[]` | `-` | Horizontal reference lines (y-values only) rendered on the sparkline | --- #### Area Chart **Name:** `area-chart` An area chart component built using Recharts v3. Supports stacked areas, gradients, and custom tooltips. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `data` (required) | `any[]` | `-` | The data for the chart | | `categories` (required) | `string[]` | `-` | Keys in data to map to lines/areas | | `index` (required) | `string` | `-` | Key in data to use for x-axis | | `colors` | `ThemeColor[]` | `-` | Colors for each category | | `curveType` | `'linear' | 'monotone' | 'step' | '...'` | `'monotone'` | Curve interpolation type | | `connectNulls` | `boolean` | `false` | Connect area across null/undefined values | | `showDataLabels` | `boolean` | `false` | Show value labels directly on data points | | `showLegend` | `boolean` | `true` | Show chart legend | | `showGridLines` | `boolean` | `true` | Show grid lines | | `actions` | `ReactNode` | `-` | Actions to display in the chart header | | `cardProps` | `CardProps` | `-` | Props to pass to the underlying Card component | | `tooltipSortByValue` | `boolean` | `false` | Sort tooltip items by value (descending) | | `tooltipShowTotal` | `boolean` | `false` | Show total in tooltip for multi-series | | `tooltipTotalLabel` | `string` | `'Total'` | Label for the total row in tooltip | | `legendIndicator` | `'square' | 'circle' | 'line'` | `'square'` | Shape of legend indicators | | `interactiveLegend` | `boolean` | `false` | Allow clicking legend items to toggle series visibility | | `legendWrap` | `boolean` | `true` | Allow legend items to wrap to multiple lines | | `xAxisFormatter` | `(value: string) => string` | `-` | Formatter for x-axis tick labels and tooltip header | | `xAxisTick` | `SVGProps | ReactElement | ((props) => ReactNode) | boolean` | `-` | Custom tick rendering for the x-axis — overrides xAxisFormatter when set | | `yAxisFormatter` | `(value: number) => string` | `-` | Formatter for y-axis tick labels — falls back to valueFormatter | | `yAxisTick` | `SVGProps | ReactElement | ((props) => ReactNode) | boolean` | `-` | Custom tick rendering for the y-axis — overrides yAxisFormatter when set | | `referenceLines` | `ChartReferenceLine[]` | `-` | Reference lines (targets, thresholds, averages) rendered on the chart | --- #### Line Chart **Name:** `line-chart` A line chart component built using Recharts v3. Supports multi-series, dot customization, curve types, and connectNulls. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `data` (required) | `any[]` | `-` | The data for the chart | | `categories` (required) | `string[]` | `-` | Keys in data to map to lines | | `index` (required) | `string` | `-` | Key in data to use for x-axis | | `colors` | `ThemeColor[]` | `-` | Colors for each category | | `curveType` | `'linear' | 'monotone' | 'step' | '...'` | `'monotone'` | Curve interpolation type | | `showDots` | `boolean` | `true` | Show dots at data points | | `dotSize` | `number` | `4` | Dot radius in pixels | | `connectNulls` | `boolean` | `false` | Connect line across null/undefined values | | `showDataLabels` | `boolean` | `false` | Show value labels directly on data points | | `showLegend` | `boolean` | `true` | Show chart legend | | `showGridLines` | `boolean` | `true` | Show grid lines | | `actions` | `ReactNode` | `-` | Actions to display in the chart header | | `cardProps` | `CardProps` | `-` | Props to pass to the underlying Card component | | `tooltipSortByValue` | `boolean` | `false` | Sort tooltip items by value (descending) | | `tooltipShowTotal` | `boolean` | `false` | Show total in tooltip for multi-series | | `tooltipTotalLabel` | `string` | `'Total'` | Label for the total row in tooltip | | `legendIndicator` | `'square' | 'circle' | 'line'` | `'line'` | Shape of legend indicators | | `interactiveLegend` | `boolean` | `false` | Allow clicking legend items to toggle series visibility | | `legendWrap` | `boolean` | `true` | Allow legend items to wrap to multiple lines | | `xAxisFormatter` | `(value: string) => string` | `-` | Formatter for x-axis tick labels and tooltip header | | `xAxisTick` | `SVGProps | ReactElement | ((props) => ReactNode) | boolean` | `-` | Custom tick rendering for the x-axis — overrides xAxisFormatter when set | | `yAxisFormatter` | `(value: number) => string` | `-` | Formatter for y-axis tick labels — falls back to valueFormatter | | `yAxisTick` | `SVGProps | ReactElement | ((props) => ReactNode) | boolean` | `-` | Custom tick rendering for the y-axis — overrides yAxisFormatter when set | | `referenceLines` | `ChartReferenceLine[]` | `-` | Reference lines (targets, thresholds, averages) rendered on the chart | --- #### Bar Chart **Name:** `bar-chart` A bar chart component built using Recharts v3. Supports vertical/horizontal layout, stacked/grouped bars, and customizable styling. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `data` (required) | `any[]` | `-` | The data for the chart | | `categories` (required) | `string[]` | `-` | Keys in data to map to bars | | `index` (required) | `string` | `-` | Key in data to use for category axis | | `colors` | `ThemeColor[]` | `-` | Colors for each category | | `layout` | `'vertical' | 'horizontal'` | `'vertical'` | Bar orientation | | `stacked` | `boolean` | `false` | Stack bars on top of each other | | `barRadius` | `number` | `4` | Corner radius for bars | | `barGap` | `number` | `4` | Gap between grouped bars | | `showDataLabels` | `boolean` | `false` | Show value labels directly on bars | | `showLegend` | `boolean` | `true` | Show chart legend | | `showGridLines` | `boolean` | `true` | Show grid lines | | `actions` | `ReactNode` | `-` | Actions to display in the chart header | | `cardProps` | `CardProps` | `-` | Props to pass to the underlying Card component | | `tooltipSortByValue` | `boolean` | `false` | Sort tooltip items by value (descending) | | `tooltipShowTotal` | `boolean` | `false` | Show total in tooltip for multi-series | | `tooltipTotalLabel` | `string` | `'Total'` | Label for the total row in tooltip | | `legendIndicator` | `'square' | 'circle' | 'line'` | `'square'` | Shape of legend indicators | | `interactiveLegend` | `boolean` | `false` | Allow clicking legend items to toggle series visibility | | `legendWrap` | `boolean` | `true` | Allow legend items to wrap to multiple lines | | `xAxisFormatter` | `(value: string) => string` | `-` | Formatter for x-axis (category axis) tick labels and tooltip header | | `xAxisTick` | `SVGProps | ReactElement | ((props) => ReactNode) | boolean` | `-` | Custom tick rendering for the category axis — overrides xAxisFormatter when set | | `yAxisFormatter` | `(value: number) => string` | `-` | Formatter for y-axis (value axis) tick labels — falls back to valueFormatter | | `yAxisTick` | `SVGProps | ReactElement | ((props) => ReactNode) | boolean` | `-` | Custom tick rendering for the value axis — overrides yAxisFormatter when set | | `referenceLines` | `ChartReferenceLine[]` | `-` | Reference lines (targets, thresholds, averages) rendered on the chart | --- #### Pie Chart **Name:** `pie-chart` A pie/donut chart component built using Recharts v3. Supports donut variant with center labels, slice labels, and customizable styling. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `data` (required) | `{ name: string; value: number }[]` | `-` | The data for the chart - each item becomes a slice | | `colors` | `ThemeColor[]` | `-` | Colors for each slice | | `variant` | `'pie' | 'donut'` | `'pie'` | Chart style | | `innerRadius` | `number | string` | `60` | Inner radius for donut variant | | `outerRadius` | `number | string` | `80` | Outer radius | | `showLabels` | `boolean` | `false` | Show value labels on slices | | `showDataLabels` | `boolean` | `false` | Show value labels on slices (alias for showLabels for cross-chart consistency) | | `labelType` | `'value' | 'percent' | 'name'` | `'value'` | Label content type | | `paddingAngle` | `number` | `0` | Gap between slices in degrees | | `centerLabel` | `{ value: string | number; label?: string }` | `-` | Center label for donut charts | | `showLegend` | `boolean` | `true` | Show chart legend | | `cardProps` | `CardProps` | `-` | Props to pass to the underlying Card component | | `tooltipSortByValue` | `boolean` | `false` | Sort tooltip items by value (descending) | | `legendIndicator` | `'square' | 'circle' | 'line'` | `'square'` | Shape of legend indicators | | `legendShowValues` | `boolean` | `false` | Show values in legend | | `legendWrap` | `boolean` | `true` | Allow legend items to wrap to multiple lines | --- #### Radial Chart **Name:** `radial-chart` A radial/gauge chart component built using Recharts v3. Supports progress gauges, multi-value radial bars, and customizable angles. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `data` (required) | `{ name: string; value: number }[]` | `-` | The data for the chart - each item becomes a radial bar | | `colors` | `ThemeColor[]` | `-` | Colors for each bar | | `startAngle` | `number` | `90` | Start angle in degrees | | `endAngle` | `number` | `-270` | End angle in degrees | | `innerRadius` | `number | string` | `"30%"` | Inner radius | | `outerRadius` | `number | string` | `"100%"` | Outer radius | | `barSize` | `number` | `10` | Thickness of radial bars | | `showBackground` | `boolean` | `true` | Show background track | | `cornerRadius` | `number` | `5` | Corner radius for bars | | `max` | `number` | `100` | Maximum value for the scale | | `centerLabel` | `{ value: string | number; label?: string }` | `-` | Center label for gauge-style display | | `cardProps` | `CardProps` | `-` | Props to pass to the underlying Card component | | `tooltipSortByValue` | `boolean` | `false` | Sort tooltip items by value (descending) | | `legendIndicator` | `'square' | 'circle' | 'line'` | `'square'` | Shape of legend indicators | | `legendShowValues` | `boolean` | `false` | Show values in legend | | `legendWrap` | `boolean` | `true` | Allow legend items to wrap to multiple lines | --- #### Combined Chart **Name:** `combined-chart` A combined bar + line chart component built using Recharts v3. Overlay bars and lines in a single chart for comparative analysis. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `data` (required) | `any[]` | `-` | The data for the chart | | `index` (required) | `string` | `-` | Key in data to use for x-axis | | `barCategories` (required) | `string[]` | `-` | Keys in data to render as bars | | `lineCategories` (required) | `string[]` | `-` | Keys in data to render as lines | | `barColors` | `ThemeColor[]` | `-` | Colors for bar series | | `lineColors` | `ThemeColor[]` | `-` | Colors for line series | | `stacked` | `boolean` | `false` | Stack bar series | | `showDots` | `boolean` | `true` | Show dots on lines | | `connectNulls` | `boolean` | `false` | Connect lines across null/undefined values | | `showDataLabels` | `boolean` | `false` | Show value labels directly on chart elements | | `barRadius` | `number` | `4` | Corner radius for bars | | `cardProps` | `CardProps` | `-` | Props to pass to the underlying Card component | | `tooltipSortByValue` | `boolean` | `false` | Sort tooltip items by value (descending) | | `tooltipShowTotal` | `boolean` | `false` | Show total in tooltip for multi-series | | `tooltipTotalLabel` | `string` | `'Total'` | Label for the total row in tooltip | | `legendIndicator` | `'square' | 'circle' | 'line'` | `'square'` | Shape of legend indicators | | `interactiveLegend` | `boolean` | `false` | Allow clicking legend items to toggle series visibility | | `legendWrap` | `boolean` | `true` | Allow legend items to wrap to multiple lines | | `xAxisFormatter` | `(value: string) => string` | `-` | Formatter for x-axis tick labels and tooltip header | | `xAxisTick` | `SVGProps | ReactElement | ((props) => ReactNode) | boolean` | `-` | Custom tick rendering for the x-axis — overrides xAxisFormatter when set | | `yAxisFormatter` | `(value: number) => string` | `-` | Formatter for y-axis tick labels — falls back to valueFormatter | | `yAxisTick` | `SVGProps | ReactElement | ((props) => ReactNode) | boolean` | `-` | Custom tick rendering for the y-axis — overrides yAxisFormatter when set | | `referenceLines` | `ChartReferenceLine[]` | `-` | Reference lines (targets, thresholds, averages) rendered on the chart | --- #### Funnel Chart **Name:** `funnel-chart` A funnel chart component built using Recharts v3. Visualize stage-based conversion data with customizable colors, gradients, and glow effects. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `data` (required) | `{ name: string; value: number }[]` | `-` | The data for the chart - each item becomes a funnel segment | | `colors` | `ThemeColor[]` | `-` | Colors for each segment | | `colorStyle` | `'default' | 'gradient'` | `'gradient'` | Color fill style | | `glow` | `boolean` | `true` | Add glow effect behind segments | | `showLabels` | `boolean` | `true` | Show segment labels | | `labelPosition` | `'inside' | 'right' | 'left'` | `'right'` | Label placement | | `reversed` | `boolean` | `false` | Reverse funnel direction (wide at bottom) | | `showLegend` | `boolean` | `true` | Show chart legend | | `cardProps` | `CardProps` | `-` | Props to pass to the underlying Card component | | `tooltipSortByValue` | `boolean` | `false` | Sort tooltip items by value (descending) | | `legendIndicator` | `'square' | 'circle' | 'line'` | `'square'` | Shape of legend indicators | | `legendShowValues` | `boolean` | `false` | Show values in legend | | `legendWrap` | `boolean` | `true` | Allow legend items to wrap | --- #### Sankey Chart **Name:** `sankey-chart` A Sankey diagram component built using Recharts v3. Visualize flow data between nodes with customizable links, gradients, and glow effects. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `data` (required) | `{ nodes: { name: string }[]; links: { source: number; target: number; value: number }[] }` | `-` | Sankey data with nodes and links arrays | | `colors` | `ThemeColor[]` | `-` | Colors for nodes | | `colorStyle` | `'default' | 'gradient'` | `'gradient'` | Node fill style | | `glow` | `boolean` | `false` | Add glow effect behind nodes | | `nodeWidth` | `number` | `10` | Width of nodes in pixels | | `nodePadding` | `number` | `20` | Vertical padding between nodes | | `linkCurvature` | `number` | `0.5` | Link curve amount (0-1) | | `iterations` | `number` | `32` | Number of layout iterations | | `showTooltip` | `boolean` | `true` | Show tooltip on hover | | `cardProps` | `CardProps` | `-` | Props to pass to the underlying Card component | --- #### Sunburst Chart **Name:** `sunburst-chart` A sunburst chart component built using Recharts v3. Visualize hierarchical data in concentric rings with customizable colors, gradients, and glow effects. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `data` (required) | `{ name: string; value?: number; children?: SunburstDataItem[] }` | `-` | Hierarchical data tree with optional children | | `colors` | `ThemeColor[]` | `-` | Colors for rings/segments | | `colorStyle` | `'default' | 'gradient'` | `'gradient'` | Segment fill style | | `glow` | `boolean` | `true` | Add glow effect behind segments | | `innerRadius` | `number | string` | `0` | Inner radius (center hole) | | `outerRadius` | `number | string` | `'80%'` | Outer radius | | `cx` | `number | string` | `'50%'` | Center X position | | `cy` | `number | string` | `'50%'` | Center Y position | | `showLabels` | `boolean` | `true` | Show labels on segments | | `labelType` | `'value' | 'percent' | 'name'` | `'name'` | Label content type | | `showLegend` | `boolean` | `true` | Show chart legend | | `cardProps` | `CardProps` | `-` | Props to pass to the underlying Card component | | `tooltipSortByValue` | `boolean` | `false` | Sort tooltip items by value (descending) | | `legendIndicator` | `'square' | 'circle' | 'line'` | `'square'` | Shape of legend indicators | | `legendShowValues` | `boolean` | `false` | Show values in legend | | `legendWrap` | `boolean` | `true` | Allow legend items to wrap | --- #### Heatmap Chart **Name:** `heatmap-chart` A heatmap/matrix chart for visualizing value density across two dimensions. Built with custom SVG for activity grids, correlation matrices, and intensity maps. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `data` (required) | `Record[]` | `-` | Array of row objects with values for each category | | `categories` (required) | `string[]` | `-` | Column keys to render as cells | | `index` (required) | `string` | `-` | Row label field key | | `color` | `ThemeColor` | `'primary'` | Single color with intensity-based opacity | | `colorScale` | `ThemeColor[]` | `-` | Multi-color scale (2-3 stops) for gradient interpolation | | `emptyColor` | `string` | `'transparent'` | Color for null/zero cells | | `variant` | `'default' | 'gradient'` | `'default'` | Color fill variant | | `glow` | `boolean` | `false` | Add glow effect on hovered cell | | `showCellValues` | `boolean` | `false` | Render value text inside cells | | `showTooltip` | `boolean` | `true` | Show tooltip on hover | | `showXAxis` | `boolean` | `true` | Show column labels | | `showYAxis` | `boolean` | `true` | Show row labels | | `cellRadius` | `number` | `4` | Cell border radius in px | | `cellGap` | `number` | `2` | Gap between cells in px | | `valueFormatter` | `(value: number) => string` | `-` | Format cell values for display | | `cardProps` | `CardProps` | `-` | Props passed to the Card wrapper | --- #### Radar Chart **Name:** `radar-chart` A radar/spider chart component built using Recharts v3. Visualize multi-variable data across 3+ dimensions with customizable colors, gradients, glow effects, and interactive legend. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `data` (required) | `Record[]` | `-` | Chart data array — each item represents a dimension/axis | | `categories` (required) | `string[]` | `-` | Data keys to plot as radar series | | `index` (required) | `string` | `-` | Data key for the angle axis (dimension labels) | | `colors` | `ThemeColor[]` | `["primary", "blue", "green"]` | Theme colors for each category | | `variant` | `'default' | 'gradient'` | `'gradient'` | Stroke style | | `glow` | `boolean` | `true` | Add colored glow/blur effect behind radar areas | | `valueFormatter` | `(value: number) => string` | `-` | Formatter for values (tooltip & radius axis) | | `showGrid` | `boolean` | `true` | Show polar grid lines | | `showLegend` | `boolean` | `true` | Show legend | | `showTooltip` | `boolean` | `true` | Show tooltip on hover | | `showRadiusAxis` | `boolean` | `false` | Show radius axis (value scale) | | `showDots` | `boolean` | `true` | Show dots at data vertices | | `dotSize` | `number` | `4` | Dot radius in pixels | | `fillOpacity` | `number` | `-` | Fill opacity for radar areas (default: 0.3 for gradient, 0.15 for default) | | `interactiveLegend` | `boolean` | `false` | Allow clicking legend items to toggle series visibility | | `legendIndicator` | `'square' | 'circle' | 'line'` | `'line'` | Legend indicator shape | | `legendWrap` | `boolean` | `true` | Allow legend items to wrap | | `tooltipSortByValue` | `boolean` | `false` | Sort tooltip items by value (descending) | | `tooltipShowTotal` | `boolean` | `false` | Show total in tooltip for multi-series | | `tooltipTotalLabel` | `string` | `"Total"` | Label for the total row in tooltip | | `cardProps` | `CardProps` | `-` | Props passed to the Card wrapper | --- #### Scatter Chart **Name:** `scatter-chart` A scatter/bubble chart component built using Recharts v3. Visualize two-variable correlation data with series-based API, bubble mode via zKey, customizable colors, gradients, glow effects, and interactive legend. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `series` (required) | `ScatterSeries[]` | `-` | Array of series, each with a name and data array | | `xKey` (required) | `string` | `-` | Data key for x-axis values | | `yKey` (required) | `string` | `-` | Data key for y-axis values | | `zKey` | `string` | `-` | Data key for dot size (bubble mode) | | `zRange` | `[number, number]` | `[4, 20]` | Min/max dot radius for bubble mode | | `colors` | `ThemeColor[]` | `["primary", "blue", "green"]` | Theme colors for each series | | `variant` | `'default' | 'gradient'` | `'gradient'` | Stroke style | | `glow` | `boolean` | `true` | Add colored glow/blur effect behind dots | | `dotSize` | `number` | `6` | Base dot radius (when no zKey) | | `shape` | `'circle' | 'cross' | 'diamond' | 'square' | 'star' | 'triangle' | 'wye'` | `'circle'` | Recharts native dot shape | | `valueFormatter` | `(value: number) => string` | `-` | Formatter for values in tooltip | | `xAxisFormatter` | `(value: number) => string` | `-` | Formatter for x-axis tick labels | | `yAxisFormatter` | `(value: number) => string` | `-` | Formatter for y-axis tick labels | | `xLabel` | `string` | `-` | X-axis label | | `yLabel` | `string` | `-` | Y-axis label | | `showXAxis` | `boolean` | `true` | Show x-axis | | `showYAxis` | `boolean` | `true` | Show y-axis | | `showGridLines` | `boolean` | `true` | Show grid lines | | `showLegend` | `boolean` | `true` | Show legend | | `showTooltip` | `boolean` | `true` | Show tooltip on hover | | `autoMinValue` | `boolean` | `false` | Auto-calculate min value for axes | | `referenceLines` | `ChartReferenceLine[]` | `-` | Reference lines (targets, thresholds, averages) | | `interactiveLegend` | `boolean` | `false` | Allow clicking legend items to toggle series visibility | | `legendIndicator` | `'square' | 'circle' | 'line'` | `'circle'` | Legend indicator shape | | `legendWrap` | `boolean` | `true` | Allow legend items to wrap | | `tooltipSortByValue` | `boolean` | `false` | Sort tooltip items by value (descending) | | `cardProps` | `CardProps` | `-` | Props passed to the Card wrapper | --- ### Navigation #### Tabs **Name:** `tabs` Versatile tab component with glass styling, animated indicators, badge support, and compound component pattern for content panels. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `value` | `T extends string` | `-` | Currently selected tab value | | `onValueChange` | `(value: T) => void` | `-` | Callback when selection changes | | `fullWidth` | `boolean` | `false` | Whether tabs should take full width of container | | `animation` | `'fade' | 'slide'` | `'fade'` | Animation type for the active indicator | | `variant` | `'normal' | 'subtle' | 'strong' | 'solid' | 'none'` | `'subtle'` | Visual variant of the container background | | `indicatorVariant` | `'gradient' | 'color' | 'glass' | 'solid'` | `'gradient'` | Visual variant for the active indicator. 'gradient' shows colorful gradient, 'color' shows flat solid color, 'glass' for glassmorphism, 'solid' for opaque background. | | `colorCrossfade` | `boolean` | `false` | Enable animated color crossfade when switching tabs. Only applies with animation='slide' and indicatorVariant='gradient'. Uses hardcoded hex values, so primary/secondary use fallback colors rather than theme CSS variables. | | `color` | `ThemeColor` | `'primary'` | Base color for the active indicator | | `align` | `'start' | 'center' | 'end' | 'grow'` | `'center'` | Alignment of tabs within the container | | `size` | `'sm' | 'md' | 'lg'` | `'md'` | Size variant affecting padding and font size | | `invert` | `boolean` | `false` | Invert glass overlay (light-on-light, dark-on-dark) | | `barRadius` | `'none' | 'sm' | 'default' | 'lg' | 'full'` | `'full'` | Border radius for the outer container | | `tabRadius` | `'none' | 'sm' | 'default' | 'lg' | 'full'` | `'full'` | Border radius for individual tabs | | `shadow` | `'none' | 'sm' | 'md' | 'lg'` | `'none'` | Shadow style for the container | | `leftSection` | `ReactNode` | `-` | Content to render at the start of the tab bar | | `rightSection` | `ReactNode` | `-` | Content to render at the end of the tab bar | | `className` | `string` | `-` | Additional CSS classes for the container | | `tabClassName` | `string` | `-` | Additional CSS classes for each tab item | **Compound Components:** - `Tabs.Tab` Individual tab button with icon, badge, and color support - `Tabs.Content` Content panel that shows when corresponding tab is active - `TabsSkeleton` Server-compatible loading skeleton for Tabs. Accepts same layout props as Tabs for perfect matching. --- #### Breadcrumb **Name:** `breadcrumb` A breadcrumb navigation component with glass styling, multiple separator styles, size variants, and automatic truncation with dropdown. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `items` (required) | `BreadcrumbItem[]` | `-` | Array of breadcrumb items with label, href, and optional icon | | `variant` | `'normal' | 'subtle' | 'none'` | `'none'` | Glass effect variant | | `invert` | `boolean` | `false` | Invert glass overlay | | `size` | `'sm' | 'md' | 'lg'` | `'md'` | Size variant | | `radius` | `'none' | 'sm' | 'default' | 'lg' | 'full'` | `'default'` | Container border radius | | `separator` | `'slash' | 'chevron' | 'arrow' | 'dot'` | `'chevron'` | Separator style between items | | `maxItems` | `number` | `-` | Max visible items (truncates middle with dropdown) | | `itemClassName` | `string` | `-` | Additional classes for each breadcrumb item | --- #### Sidebar **Name:** `sidebar` A full-featured collapsible sidebar with compound components, mobile Sheet support, nested items, search filtering, badges, and multiple visual variants. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `variant` | `'floating' | 'fixed' | 'inline'` | `'floating'` | Visual style variant | | `type` | `'normal' | 'subtle' | 'strong' | 'solid' | 'none'` | `'normal'` | Glass type for styling | | `invert` | `boolean` | `false` | Invert glass overlay (white-on-light, dark-on-dark) | | `radius` | `'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'` | `'md'` | Border radius size | | `border` | `boolean` | `true` | Show border around sidebar (variant-aware: all sides for floating, right side only for fixed/inline) | | `collapsible` | `boolean` | `false` | Enable collapse to icons mode | | `defaultCollapsed` | `boolean` | `false` | Initial collapsed state | | `collapsed` | `boolean` | `-` | Controlled collapsed state | | `onCollapsedChange` | `(collapsed: boolean) => void` | `-` | Callback when collapsed state changes | | `mobileBreakpoint` | `'sm' | 'md' | 'lg'` | `'lg'` | When to show mobile drawer | | `width` | `number` | `256` | Width in pixels | | `collapsedWidth` | `number` | `64` | Width when collapsed | | `activePath` | `string` | `-` | Current active path for highlighting | | `activeStyle` | `'background' | 'accentBar' | 'underline' | 'text'` | `'background'` | Active item styling variant | | `accentColor` | `ThemeColor` | `'primary'` | Accent color for active items | | `accentPosition` | `'left' | 'right'` | `'left'` | Position of accent bar | | `hoverEffect` | `'none' | 'scale' | 'glow' | 'scale-glow' | 'translate'` | `'none'` | Hover animation effect for items | | `className` | `string` | `-` | Additional CSS classes | **Compound Components:** - `Sidebar.Header` The header container. - `Sidebar.Content` The scrollable content area. - `Sidebar.Footer` The footer container. - `Sidebar.Group` A grouping of sidebar items with optional borders and collapse behavior. - `Sidebar.Item` An interactive sidebar item. - `Sidebar.Label` Animated text label for an item. - `Sidebar.Icon` Icon wrapper for an item. - `Sidebar.Action` Trailing action for an item. - `Sidebar.SubItems` Container for nested sub-items with optional left border. - `Sidebar.Separator` A visual divider between groups or sections. --- ### Layout #### Header **Name:** `header` A flexible section header component with icon, title, description, size variants, action slots, and configurable heading level for accessibility. Includes staggered reveal animation, icon hover effects, loading skeleton state, and compound components for custom layouts. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `title` (required) | `string` | `-` | The title text | | `size` | `'sm' | 'md' | 'lg' | 'xl'` | `'md'` | Size variant affecting font size and semantic heading level (xl=h1, lg=h2, md=h3, sm=h4) | | `description` | `string` | `-` | The description text below the title | | `icon` | `LucideIcon` | `-` | The icon to display (from lucide-react) | | `actions` | `ReactNode` | `-` | Content to render in the actions area (right side). Use Fragment to compose multiple items. | | `loading` | `boolean` | `false` | Shows skeleton loading state when true | | `animated` | `boolean` | `true` | Whether to animate the entrance with staggered fade-in and slide-up effects | | `className` | `string` | `-` | Additional CSS classes for the container | | `titleClassName` | `string` | `-` | Additional CSS classes for the title | | `iconClassName` | `string` | `-` | Additional CSS classes for the icon | | `iconContainerClassName` | `string` | `-` | Additional CSS classes for the icon container | **Compound Components:** - `Header.Root` The root container for the header. - `Header.Description` A description text component for the header. - `Header.Actions` A container for header actions (buttons, etc.). --- #### Image Gallery **Name:** `image-gallery` A flexible image gallery with grid/scroll layouts, lightbox modal, hover effects, and compound component pattern for full customization. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `images` | `ImageGalleryImage[]` | `-` | Array of images for data-driven mode | | `type` | `'normal' | 'subtle' | 'strong' | 'solid' | 'none'` | `'normal'` | Glass styling type | | `hoverEffect` | `'none' | 'overlay'` | `'overlay'` | Hover effect - overlay shows alt text with blur | | `overlayStyle` | `'dark' | 'light' | 'gradient'` | `'dark'` | Overlay style when hoverEffect is 'overlay' | | `aspectRatio` | `'square' | 'video' | 'wide' | 'portrait'` | `'video'` | Default aspect ratio for items | | `borderRadius` | `'none' | 'sm' | 'md' | 'lg'` | `'md'` | Default border radius for items | | `ImageComponent` | `React.ComponentType` | `'img'` | Custom image component (e.g., Next.js Image) | | `cardProps` | `Partial` | `-` | Card component props for customization | | `className` | `string` | `-` | Additional CSS classes | **Compound Components:** - `ImageGallery.Header` Header with title, icon, description, and action children - `ImageGallery.Grid` Responsive grid layout with standard or bento mode - `ImageGallery.Scroll` Horizontal scroll layout with navigation arrows - `ImageGallery.Item` Single image thumbnail - `ImageGallery.Lightbox` Modal viewer with keyboard navigation - `ImageGallery.Empty` Empty state placeholder --- #### Info Bar **Name:** `info-bar` An announcement/alert bar component with glass styling, icons, actions, and dismissible functionality. Supports multiple variants, accent bars, and CSS enter animations. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `variant` | `'info' | 'success' | 'warning' | 'error'` | `'info'` | Intent-based styling variant | | `type` | `CardType` | `'normal'` | Glass effect variant | | `invert` | `boolean` | `false` | Invert glass overlay | | `accentBar` | `'none' | 'left' | 'top'` | `'left'` | Accent bar position | | `accentColor` | `ThemeColor` | `-` | Override accent color (defaults from variant) | | `title` | `string` | `-` | Main message title | | `description` | `string` | `-` | Secondary description text | | `icon` | `React.ComponentType` | `-` | Custom icon (defaults based on variant) | | `actions` | `React.ReactNode` | `-` | Action buttons/links | | `dismissible` | `boolean` | `false` | Show close button | | `onDismiss` | `() => void` | `-` | Callback when dismissed | | `animation` | `'none' | 'fade' | 'slide-down' | 'slide-left'` | `'none'` | Enter animation type (CSS-only) | | `animationDuration` | `number` | `500` | Animation duration in ms | --- #### Entity Grid **Name:** `entity-grid` A composable grid component for displaying entity collections. Uses compound components (EntityGrid.Header, EntityGrid.Content, EntityGrid.Empty, EntityGrid.Error, EntityGrid.Stats, EntityGrid.Filters) for flexible layouts. Supports EntityCard mode, ImageCard mode, or custom render functions. Two loading variants: skeleton or blurred overlay. Flexible ID handling with keyExtractor prop. Built-in SectionHeader and EnhancedEmptyState integration. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `data` (required) | `T[] | undefined` | `-` | Array of entities to display (extends BaseEntity). If undefined, automatically triggers loading state. | | `keyExtractor` | `(item: T, index: number) => string | number` | `-` | Function to extract unique key from entity. Default: tries _id, id, key, then falls back to index | | `children` (required) | `ReactNode` | `-` | Compound components: EntityGrid.Header, EntityGrid.Content, EntityGrid.Empty, EntityGrid.Error | | `grid` | `GridPreset | GridColumns` | `'4-col'` | Grid columns config: preset ('2-col', '3-col', '4-col', '6-col') or custom breakpoint object | | `gap` | `'sm' | 'md' | 'lg'` | `'md'` | Gap between grid items | | `loading` | `boolean` | `false` | Shows loading state when true | | `loadingVariant` | `'skeleton' | 'overlay'` | `'skeleton'` | Loading display: skeleton cards or blurred overlay with spinner | | `loadingCount` | `number` | `6` | Number of skeleton items to show when loading | | `error` | `Error | null` | `-` | Error object if data fetching failed | | `className` | `string` | `-` | Additional CSS classes for the container | | `stagger` | `'none' | 'fade' | 'slide-up' | 'slide-down' | 'scale' | 'fade-slide'` | `'none'` | Stagger animation preset for grid items entering the view | | `staggerDelay` | `number` | `0.05` | Delay in seconds between each staggered item animation | | `gridVariant` | `'standard' | 'bento'` | `'standard'` | Grid layout variant. 'bento' enables asymmetric layouts with col/row spans. | | `bentoLayout` | `BentoSpan[]` | `-` | Array of span configurations for bento grid. Each item defines colSpan and rowSpan (can be responsive objects). Pattern repeats for items beyond array length. | | `bentoColumns` | `number | GridColumns` | `4` | Number of columns for bento grid. Can be a fixed number or responsive breakpoint object. | | `cardHeight` | `number` | `200` | Height in pixels for each grid row (used in gridAutoRows). Cards with rowSpan > 1 will be multiples of this height. | **Compound Components:** - `EntityGrid.Header` The header section of the grid. - `EntityGrid.Content` The main content area displaying the grid. - `EntityGrid.Empty` The empty state display. - `EntityGrid.Error` The error state display. - `EntityGrid.Stats` A section for displaying statistics. - `EntityGrid.Filters` A popover-based filter section. --- #### Timeline **Name:** `timeline` A compound component timeline with center/left/right alignment, motion animations, and server-compatible skeleton. Features iconPosition prop to show icons on timeline dots or in cards. Uses Timeline.Item, Timeline.Card, Timeline.Header, and Timeline.Dot sub-components. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `alignment` | `'center' | 'left' | 'right'` | `'center'` | Timeline line position | | `color` | `ThemeColor` | `'primary'` | Theme color for line, dots, and connectors | | `iconPosition` | `'dot' | 'card'` | `'card'` | Where icons are displayed - on timeline dot or in card header | | `cardType` | `CardType` | `'normal'` | Default card style for Timeline.Card | | `cardHoverEffect` | `HoverEffect` | `'lift'` | Default hover effect for Timeline.Card | | `animation` | `'slide' | 'fade' | 'none'` | `'slide'` | Animation style for items appearing | | `className` | `string` | `-` | Additional CSS classes for the container | | `itemClassName` | `string` | `-` | Additional CSS classes for each timeline item wrapper | | `lineClassName` | `string` | `-` | Additional CSS classes for the vertical line | **Compound Components:** - `Timeline.Item` A timeline entry that positions content relative to the timeline line. - `Timeline.Card` The card component that wraps timeline item content. Integrates with the Card component. - `Timeline.Header` Header component for use inside Timeline.Card. Wraps the Header component with timeline-specific additions. - `Timeline.Dot` The dot/marker on the timeline. Automatically rendered by Timeline.Item but can be customized. - `Timeline.Skeleton` Server-compatible loading skeleton for the timeline. --- #### Entity Table **Name:** `entity-table` A composable table component for displaying tabular data. Uses compound components (EntityTable.Header, EntityTable.Toolbar, EntityTable.Empty, EntityTable.Error, EntityTable.Pagination) for flexible layouts. Supports sorting, searching, row selection, bulk actions, column visibility, stagger animations, glass effect styling (type/invert), row density (gap), and both load-more and page-based pagination. Two loading variants: skeleton or blurred overlay. Flexible ID handling with keyExtractor prop. No tanstack/react-table dependency. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `data` (required) | `T[] | undefined` | `-` | Array of entities to display (extends BaseEntity). If undefined, automatically triggers loading state. | | `columns` (required) | `EntityTableColumn[]` | `-` | Column definitions with key, header, sortable, cell renderer, etc. | | `keyExtractor` | `(item: T, index: number) => string | number` | `-` | Function to extract unique key from entity. Default: tries _id, id, key, then falls back to index | | `children` (required) | `ReactNode` | `-` | Compound components: EntityTable.Header, EntityTable.Toolbar, EntityTable.Empty, EntityTable.Pagination | | `actions` | `EntityTableRowAction[]` | `-` | Row actions with icon, label, onClick handler | | `selection` | `boolean` | `false` | Enable row selection with checkboxes | | `bulkActions` | `EntityTableBulkAction[]` | `-` | Actions for selected rows (requires selection=true) | | `defaultSort` | `{ key: string; direction: 'asc' | 'desc' }` | `-` | Default sort state for uncontrolled sorting | | `type` | `'normal' | 'subtle' | 'strong' | 'solid' | 'none'` | `'normal'` | Glass effect variant for table styling | | `invert` | `boolean` | `false` | Invert glass overlay (light on light, dark on dark) | | `gap` | `'compact' | 'comfortable' | 'relaxed'` | `'comfortable'` | Row padding density (compact for dense data, relaxed for readability) | | `stagger` | `'none' | 'fade' | 'slide' | 'scale'` | `'none'` | Stagger animation preset for row entrance. 'slide' slides down when adding, slides up when removing | | `staggerDelay` | `number` | `0.03` | Delay between staggered row animations in seconds | | `loading` | `boolean` | `false` | Shows loading state when true | | `loadingVariant` | `'skeleton' | 'overlay'` | `'skeleton'` | Loading display: skeleton rows or blurred overlay with spinner | | `loadingCount` | `number` | `5` | Number of skeleton rows to show when loading | | `error` | `Error | null` | `-` | Error object if data fetching failed | | `className` | `string` | `-` | Additional CSS classes for the container | **Compound Components:** - `EntityTable.Header` The header section of the table. - `EntityTable.Toolbar` A separate toolbar for search and filters. - `EntityTable.Pagination` Pagination controls. - `EntityTable.Empty` The empty state display. Extends EnhancedEmptyState props. - `EntityTable.Error` The error state display. Shows default error UI or custom content. - `EntityTable.Stats` A section for displaying statistics between header and table. - `EntityTable.Filters` A popover-based filter section. --- #### Entity Hero **Name:** `entity-hero` A hero section component for displaying entity details with full-width image background, glassmorphism panels, and animated content. Supports ViewTransition for smooth page transitions. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `entity` (required) | `T extends BaseEntity | undefined | null` | `-` | The entity data to display. Shows skeleton when undefined/null. | | `image` (required) | `HeroImage` | `-` | Image configuration with key, alt, and fallback URL | | `ImageComponent` | `React.ElementType` | `'img'` | Image component to use (e.g., next/image for Next.js) | | `panelType` | `'normal' | 'subtle' | 'strong'` | `'normal'` | Glass panel type for all content panels | | `panelInvert` | `boolean` | `true` | Use inverted glass style (light on light, dark on dark) | | `height` | `'sm' | 'md' | 'lg'` | `'md'` | Height preset (sm: 250/300px, md: 300/400px, lg: 400/500px) | | `className` | `string` | `-` | Additional CSS classes | **Compound Components:** - `EntityHero.Above` Content at the very top of the hero, above TopLeft/TopRight. Useful for embedded page headers. - `EntityHero.TopLeft` Content in the top left corner - `EntityHero.TopRight` Content in the top right corner - `EntityHero.Header` Content above the main panel (e.g., category badge) - `EntityHero.Content` Main content panel for title, description, and custom content **Usage:** ```tsx import { EntityHero } from "@/components/ui/orecus.io/layout/entity-hero"; // Full compound component pattern Featured {project.category}

{project.name}

{project.description}

 ``` --- ### Blocks #### Dashboard **Name:** `dashboard` A composable dashboard block with stats grid, charts section, and data table. Perfect for admin dashboards and analytics overviews. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `children` (required) | `ReactNode` | `-` | Dashboard compound components (Dashboard.Header, Dashboard.Stats, etc.) | | `className` | `string` | `-` | Additional CSS classes for the container | **Compound Components:** - `Dashboard.Header` Header with title, description, and actions. Extends Header component props. - `Dashboard.Stats` Grid of stat cards with configurable columns. - `Dashboard.Charts` Charts section with single, split, or triple layout. - `Dashboard.Table` Data table or grid section. - `Dashboard.Section` Custom section with optional title and actions. --- #### Entity Page **Name:** `entity-page` A full page layout composition combining breadcrumb navigation, entity hero, and content area with single or split layout modes. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `entity` (required) | `T extends BaseEntity` | `-` | The entity data to display | | `heroProps` (required) | `Omit, 'entity' | 'children'>` | `-` | Props to pass to EntityHero (entity and children are handled by EntityPage) | | `layout` | `'single' | 'split'` | `'single'` | Content layout mode | | `embedHeader` | `boolean` | `false` | Embed the header inside the hero area for a more cohesive visual | | `stickyHeader` | `boolean` | `true` | Make the header sticky (only applies when embedHeader is false) | **Compound Components:** - `EntityPage.Header` Top bar container for breadcrumb and actions with optional glass styling. - `EntityPage.Actions` Action buttons within the header. - `EntityPage.Hero` Content slots passed to the EntityHero component. - `EntityPage.Content` Main content area. - `EntityPage.SidePanel` Side panel content for split layout. Position controlled by parent sidePanelAlign prop. - `EntityPage.Footer` Footer area with optional glass styling and sticky positioning. --- #### Analytics **Name:** `analytics` A data-intensive analytics block with KPI deltas, comparison charts, breakdowns, and trend indicators. Ideal for performance dashboards. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `children` (required) | `ReactNode` | `-` | Analytics compound components (Analytics.Header, Analytics.KPIs, etc.) | | `className` | `string` | `-` | Additional CSS classes for the container | **Compound Components:** - `Analytics.Header` Header with title, date range controls, and actions. Extends Header component props. - `Analytics.KPIs` Grid of KPI stat deltas with configurable columns. - `Analytics.Chart` Main visualization chart with title and description. - `Analytics.Breakdown` Breakdown section with single, split, or triple layout. - `Analytics.Trends` Grid of trend sparklines with configurable columns. - `Analytics.Section` Custom section with optional title and actions. --- #### App Shell **Name:** `app-shell` A composable application shell layout coordinating Sidebar, Header, Main content, and Footer areas with synchronized entry animations and fixed/floating variants. **Props:** | Prop | Type | Default | Description | |------|------|---------|-------------| | `children` (required) | `ReactNode` | `-` | Main layout content (AppShell.TopBar, AppShell.Sidebar, AppShell.Header, AppShell.Main, AppShell.Footer) | | `variant` | `'sidebar-inline' | 'sidebar-floating'` | `'sidebar-inline'` | Layout variant - inline keeps sidebar in document flow, floating adds visual separation | | `sidebarType` | `'normal' | 'subtle' | 'strong' | 'solid' | 'none'` | `'solid'` | Glass type for sidebar and TopBar styling | | `sidebarInvert` | `boolean` | `false` | Invert sidebar and TopBar glass styling | | `className` | `string` | `-` | Additional CSS classes for the root container | **Compound Components:** - `AppShell.TopBar` Thin bar at top of content area with floating children container. Creates inverted corner effect at sidebar junction. - `AppShell.Sidebar` Wrapper for the Sidebar component. Handles responsive visibility and layout positioning. - `AppShell.Header` Sticky or static header area with entry animation. - `AppShell.Main` Main content area with entry animation. - `AppShell.Footer` Sticky or static footer area with entry animation. --- Generated from registry.json on 2026-02-20