staypass-admin-layout

A comprehensive React component library for building professional admin dashboards with a consistent, modern layout system.

✨ Features

• 🎨 Pre-built Layout Components - Complete dashboard layout with breadcrumbs, filters, action buttons, and table summaries
• 📊 Data Display Components - Responsive tables, pagination, and empty states
• 🎯 TypeScript First - Full type safety with comprehensive exported interfaces
• 🎨 Tailwind CSS - Fully customizable styling with Tailwind CSS
• 📱 Responsive Design - Mobile and desktop optimized layouts
• 🔧 Tree-shakeable - Import only what you need
• 🌟 Production Ready - Battle-tested in production applications
• 📦 Zero Config - Works out of the box with sensible defaults

📦 Installation

npm install staypass-admin-layout
# or
yarn add staypass-admin-layout
# or
pnpm add staypass-admin-layout

Peer Dependencies

This package requires the following peer dependencies:

npm install react@^18.3.1 react-dom@^18.3.1 react-router-dom@^6.0.0

🚀 Quick Start

1. Import Styles

Import the package styles in your main CSS file using @import:

@import "tailwindcss";
@import "staypass-admin-layout/dist/staypass-admin-layout.css";

Important: CSS must be imported using @import in CSS files, NOT in JavaScript/TypeScript files.

2. Configure Tailwind CSS

Update your tailwind.config.js to include the package components:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './src/**/*.{js,jsx,ts,tsx}',
    './node_modules/staypass-admin-layout/dist/**/*.{js,mjs}',
  ],
  theme: {
    extend: {
      gridTemplateColumns: {
        '16': 'repeat(16, minmax(0, 1fr))',
      },
    },
  },
  plugins: [],
};

3. Use Components

import React, { useState } from 'react';
import {
  ListPageLayout,
  FilterArea,
  ActionButtonsArea,
  TableSummary,
  TablePagination,
  Table,
  TableHeader,
  TableBody,
  TableRow,
  TableHead,
  TableCell,
} from 'staypass-admin-layout';

function DashboardPage() {
  const [filters, setFilters] = useState({
    search: '',
    status: 'all',
    dateRange: { from: undefined, to: undefined },
  });

  return (
    <ListPageLayout
      title="Dashboard"
      description="Overview of your data"
      breadcrumbs={[
        { label: 'Home', href: '/' },
        { label: 'Dashboard', active: true },
      ]}
      filters={
        <FilterArea
          filters={filters}
          onFilterChange={(key, value) =>
            setFilters(prev => ({ ...prev, [key]: value }))
          }
          onApply={() => console.log('Apply filters')}
          onReset={() => setFilters({
            search: '',
            status: 'all',
            dateRange: { from: undefined, to: undefined }
          })}
        />
      }
      actions={
        <ActionButtonsArea
          showAdd
          showExport
          onAdd={() => console.log('Add')}
          onExport={() => console.log('Export')}
        />
      }
      stats={
        <TableSummary
          items={[
            { label: 'Total Users', value: 1234, color: 'blue' },
            { label: 'Active', value: 890, color: 'green' },
            { label: 'Pending', value: 123, color: 'amber' },
          ]}
        />
      }
      table={
        <Table>
          <TableHeader>
            <TableRow>
              <TableHead>Name</TableHead>
              <TableHead>Email</TableHead>
              <TableHead>Status</TableHead>
            </TableRow>
          </TableHeader>
          <TableBody>
            {/* Your table rows */}
          </TableBody>
        </Table>
      }
      pagination={
        <TablePagination
          currentPage={1}
          pageSize={10}
          totalCount={100}
          onPageChange={(page) => console.log('Page:', page)}
        />
      }
    />
  );
}

📚 Components Reference

Layout Components

ListPageLayout

The main layout component that orchestrates the entire page structure.

Props:

• title: string - Page title
• description?: string - Page description
• breadcrumbs?: BreadcrumbItemType[] - Breadcrumb navigation items
• note?: string - Info note displayed at the top
• filters?: React.ReactNode - Filter section content
• actions?: React.ReactNode - Action buttons section
• stats?: React.ReactNode - Summary statistics cards
• table: React.ReactNode - Main data table
• pagination?: React.ReactNode - Pagination controls

Navigation Components

PageBreadcrumb

Displays breadcrumb navigation with optional back button.

Props:

• items: BreadcrumbItemType[] - Array of breadcrumb items
• showBackButton?: boolean - Show back button
• onBack?: () => void - Back button click handler

Filter Components

FilterArea

Complete filter section with search, date range, and custom filters.

Props:

• filters: FilterState - Current filter state
• onFilterChange: (key: string, value: any) => void - Filter change handler
• onApply: () => void - Apply button handler
• onReset: () => void - Reset button handler
• searchPlaceholder?: string - Search input placeholder
• showDateRange?: boolean - Show date range picker (default: true)
• showSearch?: boolean - Show search input (default: true)
• checkboxFilters?: CheckboxFilter[] - Array of checkbox filters
• periodFilter?: PeriodFilterConfig - Period filter configuration

Action Components

ActionButtonsArea

Action buttons section with Add, Export, Import, and Bulk operations.

Props:

• showAdd?: boolean - Show add button (default: true)
• showExport?: boolean - Show export button (default: true)
• showImport?: boolean - Show import button (default: true)
• showBulk?: boolean - Show bulk action button (default: false)
• onAdd?: () => void - Add button handler
• onExport?: () => void - Export button handler
• onImport?: () => void - Import button handler
• onBulkDelete?: () => void - Bulk action handler
• addLabel?: string - Custom add button label
• exportLabel?: string - Custom export button label
• importLabel?: string - Custom import button label
• bulkLabel?: string - Custom bulk button label

Summary Components

TableSummary

Responsive grid of summary statistics cards with automatic column calculation.

Props:

• items: TableSummaryItem[] - Array of summary items
• className?: string - Additional CSS classes

Grid Rules:

• 1-4 items: 4 columns each
• 5 items: 3 columns each
• 6-8 items: 2 columns each
• Automatically wraps to multiple rows

Table Components

TablePagination

Simple pagination controls with Previous/Next buttons.

Props:

• currentPage: number - Current page number
• pageSize: number - Items per page
• totalCount: number - Total number of items
• onPageChange: (page: number) => void - Page change handler
• className?: string - Additional CSS classes

Shared Components

EmptyState

Displays an empty state message when no data is available.

Props:

• title?: string - Empty state title (default: "No data to display")
• description?: string - Empty state description
• icon?: React.ReactNode - Custom icon component
• className?: string - Additional CSS classes

GridContainer & GridItem

16-column grid system for custom layouts.

GridItem Props:

• children: React.ReactNode - Content
• cols: 1 | 2 | ... | 16 - Number of columns to span
• className?: string - Additional CSS classes

🎨 Styling & Customization

The package uses Tailwind CSS with CSS custom properties for theming. You can customize colors, spacing, and other design tokens by overriding the CSS variables in your own stylesheet:

:root {
  --primary: 0 0% 5%;
  --primary-foreground: 0 0% 98%;
  --secondary: 0 0% 96%;
  /* ... other variables */
}

📖 Examples

See EXAMPLE.md for detailed usage examples including:

• Complete dashboard page
• Filter-only implementation
• Custom grid layouts
• TypeScript type usage

🔧 Development

# Install dependencies
npm install

# Build the package
npm run build

# Run linting
npm run lint

📄 License

MIT © StayPass Team

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🐛 Issues

Found a bug or have a feature request? Please open an issue.

📮 Support

For questions and support, please use GitHub Discussions.