@mdxui/screenshots

Dashboard component library for screenshot generation and marketing visuals.

Note: This package is in active development. Core components (grids, KPIs, charts, tables) are currently being migrated from apps/screenshots. See Component Status below.

Features

• 90+ dashboard components - KPIs, charts, tables, lists, and more
• 35+ grid layouts - From simple columns to complex bento grids
• Multiple variants - 9 sidebars, 4 headers, browser frames
• Type-safe - Full TypeScript with mdxui prop types
• Visual regression tested - Pixel-perfect consistency guaranteed
• Theme-ready - Compatible with shadcn/ui CSS variables

Installation

pnpm add @mdxui/screenshots @mdxui/primitives
# or
npm install @mdxui/screenshots @mdxui/primitives

Peer Dependencies

{
  "@mdxui/primitives": "^0.0.0 || ^1.0.0",
  "react": "^18.0.0 || ^19.0.0"
}

Quick Start

import { DashboardShell, BrowserFrame } from '@mdxui/screenshots'
import { BreadcrumbHeader } from '@mdxui/screenshots/headers'
import { FullSidebar } from '@mdxui/screenshots/sidebars'

export function DashboardDemo() {
  return (
    <BrowserFrame url="app.example.com.ai">
      <DashboardShell
        sidebar={<FullSidebar />}
        header={<BreadcrumbHeader items={[
          { label: 'Dashboard', href: '/' },
          { label: 'Analytics' }
        ]} />}
      >
        <div className="p-4">
          {/* Your dashboard content */}
        </div>
      </DashboardShell>
    </BrowserFrame>
  )
}

Component Catalog

Layout Components

Shell & Frames

import { DashboardShell } from '@mdxui/screenshots/shell'
import { BrowserFrame } from '@mdxui/screenshots/frames'

• DashboardShell - Complete dashboard layout with sidebar, header, and content
• BrowserFrame - Browser window chrome for screenshots

Grid Layouts (35+)

Status: Coming soon - Currently in apps/screenshots, migration in progress

| Pattern | Component | Slots | Description | |---------|-----------|-------|-------------| | Single row | Grid1, Grid2, Grid3, Grid4 | 1-4 | Horizontal layouts | | Square | Grid2x2, Grid3x3, Grid4x4 | 4-16 | Symmetric grids | | Asymmetric | Grid1x2, Grid2x1, Grid3x1 | 2-4 | Multi-row layouts | | Complex | Grid1x2x1, Grid2x2x1, Grid3x2x1 | 4-6 | Mixed rows | | Special | GridBento, GridSplit13, GridSplit23 | 2-5 | Bento/sidebar layouts |

Header Variants

import {
  BreadcrumbHeader,
  TabsHeader,
  SearchHeader,
  MinimalHeader
} from '@mdxui/screenshots/headers'

• BreadcrumbHeader - Navigation breadcrumbs with optional actions
• TabsHeader - Tab-based page navigation
• SearchHeader - Search-focused header with global search
• MinimalHeader - Clean, minimal header

Example:

<BreadcrumbHeader
  items={[
    { label: 'Home', href: '/' },
    { label: 'Dashboard', href: '/dashboard' },
    { label: 'Analytics' }
  ]}
/>

<TabsHeader
  tabs={[
    { value: 'overview', label: 'Overview' },
    { value: 'analytics', label: 'Analytics' },
    { value: 'reports', label: 'Reports' }
  ]}
  defaultValue="overview"
/>

Sidebar Variants

Status: Coming soon - Currently in apps/screenshots, migration in progress

import {
  FullSidebar,
  CompactSidebar,
  IconOnlySidebar,
  GroupedSidebar,
  MinimalSidebar,
  DropdownsSidebar,
  FileTreeSidebar,
  WorkspacesSidebar,
  CalendarSidebar
} from '@mdxui/screenshots/sidebars'

• FullSidebar - Complete navigation with labels, icons, badges
• CompactSidebar - Condensed labels, full icons
• IconOnlySidebar - Icons only, tooltips on hover
• GroupedSidebar - Organized by section groups
• MinimalSidebar - Clean, minimal navigation
• DropdownsSidebar - Collapsible dropdown sections
• FileTreeSidebar - Hierarchical file tree navigation
• WorkspacesSidebar - Multi-workspace switcher
• CalendarSidebar - Calendar-focused sidebar

KPI Components

Status: Coming soon - Currently in apps/screenshots, migration in progress

import {
  KpiCard,
  KpiMini,
  KpiSparkline,
  KpiProgress,
  KpiStatus,
  KpiStats
} from '@mdxui/screenshots/panels/kpi'

• KpiCard - Standard KPI with icon, value, and change indicator
• KpiMini - Compact single-stat display
• KpiSparkline - KPI with inline sparkline chart
• KpiProgress - KPI with progress bar toward goal
• KpiStatus - Health score with color-coded indicator
• KpiStats - KPI with area chart background

Example:

<KpiCard
  label="Revenue"
  value="$45,231"
  change="+20.1%"
  changeType="positive"
  icon={<DollarSign />}
/>

<KpiSparkline
  label="Active Users"
  value="2,350"
  data={[120, 150, 180, 200, 220, 240]}
  trend="up"
/>

Chart Components

Status: Coming soon - Currently in apps/screenshots, migration in progress

import {
  ChartLine,
  ChartLineMulti,
  ChartBar,
  ChartBarGrouped,
  ChartBarStacked,
  ChartAreaGradient,
  ChartAreaStacked,
  ChartPie,
  ChartDonut,
  ChartRadial,
  ChartRadar,
  Timeline
} from '@mdxui/screenshots/panels/charts'

Line Charts

• ChartLine, ChartLineMulti

Bar Charts

• ChartBar, ChartBarGrouped, ChartBarStacked
• ChartBarHorizontal, ChartBarLabel, ChartBarMultiple

Area Charts

• ChartAreaGradient, ChartAreaStacked, ChartAreaFull

Circular Charts

• ChartPie, ChartDonut (ChartDonutFull)
• ChartRadial, ChartRadialStacked

Other

• ChartRadar, Timeline, ChartComparisonFull

Built on Recharts with responsive sizing and theme integration.

Table Components

Status: Coming soon - Currently in apps/screenshots, migration in progress

import { DataTableFull } from '@mdxui/screenshots/panels/tables'
import {
  CellBadge,
  CellProgress,
  CellSparkline,
  CellUser,
  CellStatus,
  // ... 20+ cell types
} from '@mdxui/screenshots/cells'

Table Components

• DataTableFull - Full-featured data table
• TablePagination - Pagination controls
• TableColumnHeader - Sortable column headers
• ExpandableRow - Expandable row details

Cell Types (20+)

• CellText, CellLink, CellBadge, CellStatus, CellPriority
• CellProgress, CellRating, CellDelta, CellTrend
• CellDate, CellDateTime, CellDuration, CellRelativeTime
• CellUser, CellSparkline, CellBarSpark
• CellCheckbox, CellActions, CellSecret, CellTokensBreakdown

List Components

Status: Coming soon - Currently in apps/screenshots, migration in progress

import {
  ListSimple,
  ListNotifications,
  ListTasks,
  ListLeaderboard,
  ListWorkStream,
  ListMetrics
} from '@mdxui/screenshots/panels/lists'

• ListSimple - Basic list layout
• ListNotifications - Notification feed with timestamps
• ListTasks - Task list with checkboxes and priorities
• ListLeaderboard - Ranked list with avatars and scores
• ListWorkStream - Activity stream with timeline
• ListMetrics - Metric comparison list

Sub-path Imports

The package uses sub-path exports for tree-shaking:

// Specific sub-modules
import { Grid2x2 } from '@mdxui/screenshots/grids'
import { KpiCard } from '@mdxui/screenshots/panels/kpi'
import { ChartLine } from '@mdxui/screenshots/panels/charts'
import { DataTableFull } from '@mdxui/screenshots/panels/tables'
import { ListTasks } from '@mdxui/screenshots/panels/lists'
import { CellBadge } from '@mdxui/screenshots/cells'
import { FullSidebar } from '@mdxui/screenshots/sidebars'
import { BreadcrumbHeader } from '@mdxui/screenshots/headers'
import { BrowserFrame } from '@mdxui/screenshots/frames'
import { DashboardShell } from '@mdxui/screenshots/shell'
import { cn } from '@mdxui/screenshots/utils'

Theming

Uses CSS variables compatible with shadcn/ui themes:

:root {
  --background: 0 0% 100%;
  --foreground: 240 10% 3.9%;
  --card: 0 0% 100%;
  --card-foreground: 240 10% 3.9%;
  --popover: 0 0% 100%;
  --popover-foreground: 240 10% 3.9%;
  --primary: 240 5.9% 10%;
  --primary-foreground: 0 0% 98%;
  --secondary: 240 4.8% 95.9%;
  --secondary-foreground: 240 5.9% 10%;
  --muted: 240 4.8% 95.9%;
  --muted-foreground: 240 3.8% 46.1%;
  --accent: 240 4.8% 95.9%;
  --accent-foreground: 240 5.9% 10%;
  --destructive: 0 84.2% 60.2%;
  --destructive-foreground: 0 0% 98%;
  --border: 240 5.9% 90%;
  --input: 240 5.9% 90%;
  --ring: 240 5.9% 10%;
  --radius: 0.5rem;
}

.dark {
  --background: 240 10% 3.9%;
  --foreground: 0 0% 98%;
  /* ... */
}

Custom Theming

All components use the cn() utility for class merging, allowing easy customization:

<BrowserFrame className="shadow-2xl border-2 border-primary">
  <DashboardShell className="bg-gradient-to-br from-background to-muted">
    {/* content */}
  </DashboardShell>
</BrowserFrame>

Component Status

| Category | Status | Location | |----------|--------|----------| | Headers | ✅ Available | @mdxui/screenshots/headers | | Frames | ✅ Available | @mdxui/screenshots/frames | | Shell | ✅ Available | @mdxui/screenshots/shell | | Grids | 🚧 Migration in progress | apps/screenshots | | KPIs | 🚧 Migration in progress | apps/screenshots | | Charts | 🚧 Migration in progress | apps/screenshots | | Tables | 🚧 Migration in progress | apps/screenshots | | Lists | 🚧 Migration in progress | apps/screenshots | | Cells | 🚧 Migration in progress | apps/screenshots | | Sidebars | 🚧 Migration in progress | apps/screenshots |

Components marked as "Migration in progress" are currently available in the apps/screenshots demo app and will be migrated to this package in upcoming releases.

Examples

Complete Dashboard Screenshot

import { BrowserFrame } from '@mdxui/screenshots/frames'
import { DashboardShell } from '@mdxui/screenshots/shell'
import { BreadcrumbHeader } from '@mdxui/screenshots/headers'
// Grid, KPI, and Chart components coming soon

export function DashboardScreenshot() {
  return (
    <BrowserFrame url="analytics.example.com.ai">
      <DashboardShell
        sidebar={<FullSidebar />}
        header={<BreadcrumbHeader items={[
          { label: 'Dashboard' },
          { label: 'Analytics' }
        ]} />}
      >
        {/* Grid layouts and panels will be added here */}
      </DashboardShell>
    </BrowserFrame>
  )
}

Tabbed Dashboard

import { TabsHeader } from '@mdxui/screenshots/headers'

<DashboardShell
  sidebar={<CompactSidebar />}
  header={<TabsHeader
    tabs={[
      { value: 'overview', label: 'Overview' },
      { value: 'performance', label: 'Performance' },
      { value: 'users', label: 'Users' }
    ]}
    defaultValue="overview"
  />}
>
  {/* Tab content */}
</DashboardShell>

Minimal Dashboard

import { MinimalHeader } from '@mdxui/screenshots/headers'

<DashboardShell
  sidebar={<IconOnlySidebar />}
  header={<MinimalHeader title="Analytics Dashboard" />}
>
  {/* Clean, minimal dashboard */}
</DashboardShell>

Development

# Build the package
pnpm --filter @mdxui/screenshots build

# Type check
pnpm --filter @mdxui/screenshots typecheck

# Run tests
pnpm --filter @mdxui/screenshots test

API Reference

DashboardShell

Wrapper component that provides the main dashboard layout structure.

interface DashboardShellProps {
  children: React.ReactNode
  sidebar: React.ReactNode
  header: React.ReactNode
  className?: string
}

BrowserFrame

Browser window chrome for creating realistic app screenshots.

interface BrowserFrameProps {
  children: React.ReactNode
  url?: string              // Default: 'app.example.com.ai'
  showControls?: boolean    // Default: true
  className?: string
}

BreadcrumbHeader

Header with navigation breadcrumbs.

interface BreadcrumbItemType {
  label: string
  href?: string
}

interface BreadcrumbHeaderProps {
  items: BreadcrumbItemType[]
  className?: string
}

TabsHeader

Header with tab navigation.

interface TabItem {
  value: string
  label: string
}

interface TabsHeaderProps {
  tabs: TabItem[]
  defaultValue?: string
  className?: string
}

SearchHeader

Header with global search input.

interface SearchHeaderProps {
  placeholder?: string
  className?: string
}

MinimalHeader

Simple header with just a title.

interface MinimalHeaderProps {
  title?: string
  className?: string
}

Architecture

This package is part of the mdxui ecosystem:

mdxui                       # Type contracts
  ↓
@mdxui/primitives          # Core UI primitives
  ↓
@mdxui/screenshots         # Dashboard components for screenshots

Components are designed to work with:

• @mdxui/beacon - Site template components
• @mdxui/cockpit - App template components
• @mdxui/widgets - Complex interactive widgets

Dependencies

• @mdxui/primitives - Core UI primitives (Sidebar, etc.)
• recharts - Chart library (v2.15.0)
• lucide-react - Icon library
• date-fns - Date formatting
• shiki - Code syntax highlighting
• clsx + tailwind-merge - Class name utilities

Contributing

Components are developed and validated in apps/screenshots before being migrated to this package. See the Component Promotion Workflow for details.

License

MIT

Related Packages

• @mdxui/primitives - Core UI primitives
• @mdxui/beacon - Site template components
• @mdxui/cockpit - App template components
• @mdxui/widgets - Complex widgets
• mdxui - Type contracts

Roadmap

• [ ] Migrate grid layouts (35+ components)
• [ ] Migrate KPI components (6 components)
• [ ] Migrate chart components (20+ components)
• [ ] Migrate table components and cells (25+ components)
• [ ] Migrate list components (6 components)
• [ ] Migrate sidebar variants (9 components)
• [ ] Add Storybook stories for all components
• [ ] Add visual regression tests
• [ ] Create comprehensive documentation site
• [ ] Add screenshot generation utilities
• [ ] Support custom theme presets