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.
Installation
$ npx shadcn@latest add @orecus/entity-gridDependencies:
motionlucide-react
Registry:
@orecus/entity-card@orecus/image-card@orecus/header@orecus/enhanced-empty-state@orecus/use-reduced-motion@orecus/use-tilt-animation@orecus/enhanced-button@orecus/loading-overlaypopover
Component
Projects
Your active and completed projects
Active
Website Redesign
Progress65%
Complete overhaul of the company website
Active
Mobile App
Progress40%
Native iOS and Android application development
Completed
API Integration
Progress100%
RESTful API development for third-parties
Active
Dashboard Analytics
Progress25%
Real-time analytics dashboard
Active
Cloud Migration
Progress80%
Moving infrastructure to cloud-native architecture
Archived
Security Audit
Progress100%
Comprehensive security review and improvements
Active
Payment Gateway
Progress55%
Integration with multiple payment providers
Active
Email Automation
Progress30%
Automated email campaigns and notifications
Completed
Data Pipeline
Progress100%
ETL processes and data warehouse
Props
| Prop | Type | Default | Description |
|---|---|---|---|
data* | 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* | 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.
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | — | Actions content |
title | string | — | Title text |
description | string | — | Description text |
EntityGrid.Content
The main content area displaying the grid.
| Prop | Type | Default | Description |
|---|---|---|---|
cardMode | 'entity' | 'image' | — | The rendering mode for cards |
cardProps | object | — | Props passed to the underlying card component |
children | function | — | Custom render function (mutually exclusive with cardMode) |
EntityGrid.Empty
The empty state display.
| Prop | Type | Default | Description |
|---|---|---|---|
title | string | — | Title for the empty state |
description | string | — | Description for the empty state |
icon | LucideIcon | — | Icon for the empty state |
EntityGrid.Error
The error state display.
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | — | Custom error content |
EntityGrid.Stats
A section for displaying statistics.
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | — | Stat card components |
className | string | — | Additional CSS classes |
EntityGrid.Filters
A popover-based filter section.
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | — | Filter content |
trigger | ReactNode | — | Custom trigger element |
open | boolean | — | Controlled open state |
onOpenChange | (open: boolean) => void | — | Open state change handler |