@flowlabkit/ui

A comprehensive, TypeScript-first theme system for React applications with 8 beautiful built-in themes, advanced responsive system, full CSS variable support, and extensive customization options. Part of the FlowLabKit ecosystem for building modern React applications.

Live Demo & Documentation →

Quick Start

# Interactive installer - like Vite!  
npm create flowlabkit-app@latest my-app

# Choose your setup:
# React or Vanilla
# TypeScript or JavaScript  
# Full components or themes-only
# Select specific themes

cd my-app && npm install && npm run dev

Features

• 8 Built-in Themes: Light, Dark, Ocean, Forest, Sunset, Lavender, Cyberpunk, and Autumn themes
• Advanced Responsive System: CSS-like responsive behavior with unified layout components, real-time breakpoint detection, and mobile-first design
• Dark/Light Mode: Seamless theme switching with automatic CSS variable updates
• Responsive Typography: Font size scaling (small/medium/large) with proper line heights
• Compact Mode: Space-efficient layout option for dense interfaces
• TypeScript First: Full type safety with comprehensive interfaces
• Performance Optimized: CSS variables for efficient runtime theme changes
• Persistence: LocalStorage integration for theme preferences
• Extensive Customization: Over 100 CSS variables for complete control
• Resizable Panel System: Comprehensive panel system with 10+ layout presets, full accessibility, and mobile optimization

Available Themes

• Light - Clean, professional default theme
• Dark - Modern dark theme for reduced eye strain
• Ocean - Calming blues and cyans for data-focused apps
• Forest - Natural greens for wellness and environmental apps
• Sunset - Warm oranges and pinks for creative applications
• Lavender - Soft purples for elegant, dreamy interfaces
• Cyberpunk - Neon highlights on dark backgrounds for tech/gaming
• Autumn - Cozy browns and golds for seasonal warmth

View Theme Gallery →

Interactive Installer

The fastest way to get started! Our interactive installer (create-flowlabkit-app) provides a Vite-like experience:

npm create flowlabkit-app@latest my-project

Available Templates

| Template | Framework | Language | Components | Bundle Size | |----------|-----------|----------|------------|-------------| | react-ts-full | React | TypeScript | Full Library | ~150KB | | react-ts-themes | React | TypeScript | Themes Only | ~65KB | | react-js-full | React | JavaScript | Full Library | ~150KB | | react-js-themes | React | JavaScript | Themes Only | ~65KB | | vanilla-ts | Vanilla | TypeScript | CSS Variables | ~45KB | | vanilla-js | Vanilla | JavaScript | CSS Variables | ~45KB |

Theme Selection Features

• Smart Defaults: Choose your preferred light and dark themes
• Multi-Select: Pick additional themes for variety
• Configuration Stored: Theme preferences saved in package.json
• Live Preview: See your selections before scaffolding

Installation

Interactive Installer (Recommended)

Create a new project with FlowLabKit UI pre-configured using our Vite-style interactive installer:

npm create flowlabkit-app@latest my-app

Enhanced Interactive Flow:

1. Choose Framework

• React (with full component library)
• Vanilla (pure CSS variables + themes)

2. Select Language

• TypeScript (recommended)
• JavaScript

3. Choose Setup Type

• Full Components: Complete UI library + themes
• Themes Only: Just the theme system (lighter bundle)

4. Default Light Theme

• Light, Ocean, Forest, Lavender, Autumn, or Sunset

5. Default Dark Theme

• Dark, Cyberpunk, Forest Dark, or Ocean Dark

6. Additional Themes (optional)

• Multi-select any remaining themes you want

What you get:

• 6 Templates: React TS/JS (full/themes), Vanilla TS/JS
• Pre-configured Vite with optimal settings
• Working Examples with theme switching
• Your Selected Themes ready to use
• TypeScript Support (if chosen)

Then just:

cd my-app
npm install  
npm run dev

Perfect for:

• New projects starting from scratch
• Learning FlowLabKit UI features
• Prototyping with specific themes
• Testing different framework combinations

Manual Installation

Add to existing project:

npm install @flowlabkit/ui

That's it! This installs everything: theme system, all 8 themes, and all UI components.

How it works: You install once, but import only what you need. Modern bundlers (Webpack, Vite, etc.) automatically tree-shake unused code, so you only pay for what you use!

Requirements

• React: 18.0.0 or higher (hooks required)
• TypeScript: 4.0+ (recommended for full type safety)
• Browser Support: Modern browsers with CSS Custom Properties support

Quick Start

import React from 'react';
import { 
  ThemeProvider, 
  ResponsiveProvider, 
  ResponsiveWrapper, 
  Button, 
  Card, 
  CardBody, 
  PanelGroup, 
  Panel,
  useIsMobile 
} from '@flowlabkit/ui';

function App() {
  return (
    <ThemeProvider initialConfig={{ mode: 'dark', fontSize: 'medium' }}>
      <ResponsiveProvider>
        <div style={{ minHeight: "100vh", position: 'relative' }}>
          {/* Navigation with responsive behavior */}
          <ResponsiveWrapper behavior="Navigation">
            <Navigation onPageChange={setCurrentPage} />
          </ResponsiveWrapper>

          {/* Header with responsive behavior */}
          <ResponsiveWrapper behavior="Header">
            <div style={{ display: 'flex', justifyContent: 'space-between' }}>
              <h1>FlowLabKit UI</h1>
              <Button variant="primary">Toggle Theme</Button>
            </div>
          </ResponsiveWrapper>

          {/* Content with responsive behavior */}
          <ResponsiveWrapper behavior="Content">
            <PanelGroup direction="horizontal">
              <Panel defaultSize={30} minSize={20}>
                <Card>
                  <CardBody>
                    <h2>Responsive Sidebar</h2>
                    <p>Adapts to mobile, tablet, and desktop automatically!</p>
                  </CardBody>
                </Card>
              </Panel>
              <Panel defaultSize={70}>
                <Card>
                  <CardBody>
                    <h1>Welcome to FlowLabKit UI!</h1>
                    <p>Complete with responsive design and resizable panels!</p>
                    <Button variant="primary">Get Started</Button>
                  </CardBody>
                </Card>
              </Panel>
            </PanelGroup>
          </ResponsiveWrapper>
        </div>
      </ResponsiveProvider>
    </ThemeProvider>
  );
}

Tree-Shakable Imports

After installing the package, you can import only what you need for optimal bundle sizes:

Option 1: Import Everything (~150KB)

import { ThemeProvider, Button, Card, oceanTheme } from '@flowlabkit/ui';

Option 2: Import Core Only (~45KB)

import { ThemeProvider, useTheme, lightTheme, darkTheme } from '@flowlabkit/ui/core';

Option 3: Mix and Match

// Core theme system
import { ThemeProvider } from '@flowlabkit/ui/core';
// Specific themes
import { oceanTheme, cyberpunkTheme } from '@flowlabkit/ui/themes';
// Specific components
import { Button, Card } from '@flowlabkit/ui/components';

Bundle Size by Import Strategy

| Import Strategy | Final Bundle Size | What You Get | |---------|------|-----------------| | from '@flowlabkit/ui' | ~150KB | Everything: theme system, 8 themes, all components | | from '@flowlabkit/ui/core' | ~45KB | Theme system + light/dark themes only | | from '@flowlabkit/ui/{core,themes}' | ~65KB | Core + additional themes of your choice | | from '@flowlabkit/ui/{core,components}' | ~95KB | Core + all UI components + panel system | | Custom Mix | Varies | Pick exactly what you need |

Available Components

• Form Components: Button, Input
• Display Components: Text, Badge, Image
• Navigation Components: Link
• Feedback Components: Spinner, LoadingIndicator
• Layout Components: Card, CardHeader, CardBody, CardFooter
• Panel System: PanelGroup, Panel, PanelResizeHandle, PanelPresets (10+ layouts)
• Responsive System: ResponsiveProvider, ResponsiveWrapper, useBreakpoint, useIsMobile, useOrientation, useResponsiveValue

Panel System

FlowLabKit UI includes a comprehensive resizable panel system similar to react-resizable-panels, enhanced with responsive behavior, touch support, and accessibility features.

Quick Panel Example

import { PanelGroup, Panel, PanelResizeHandle } from '@flowlabkit/ui';

function MyApp() {
  return (
    <PanelGroup direction="horizontal" className="h-screen">
      <Panel defaultSize={30} minSize={20} collapsible>
        <div>Sidebar Content</div>
      </Panel>
      <PanelResizeHandle />
      <Panel defaultSize={70}>
        <div>Main Content</div>
      </Panel>
    </PanelGroup>
  );
}

Pre-built Layout Presets

Choose from 10+ professionally designed layouts:

import { SidebarLeftLayout, DashboardLayout, EmailLayout } from '@flowlabkit/ui';

// Sidebar layout with collapsible navigation
<SidebarLeftLayout 
  sidebar={<Navigation />}
  main={<Content />}
  sidebarProps={{ minSize: 250, defaultSize: 300 }}
/>

// Dashboard with header and multiple panels
<DashboardLayout
  header={<DashboardHeader />}
  sidebar={<Sidebar />}
  main={<MainDashboard />}
  rightPanel={<ActivityFeed />}
/>

// Email-style three-panel layout
<EmailLayout
  mailList={<MailList />}
  mailContent={<MailContent />}
  mailDetails={<MailDetails />}
/>

Features

• Resizable Panels: Drag to resize, keyboard navigation, touch support
• Responsive Behavior: Automatic mobile optimizations and direction switching
• Persistence: Save panel sizes to localStorage automatically
• Accessibility: Full ARIA support, keyboard navigation, screen reader friendly
• Mobile Optimized: Touch-friendly handles, safe area support, auto-collapse
• TypeScript: Complete type safety with extensive interfaces

Full Panel Documentation →

Responsive System

FlowLabKit UI includes a comprehensive responsive system that works like CSS media queries but with React components.

Three Approaches to Responsive Design

1. ResponsiveWrapper (CSS-Like Override System)

import { ResponsiveProvider, ResponsiveWrapper } from '@flowlabkit/ui';

function ResponsiveApp() {
  return (
    <ResponsiveProvider>
      {/* Navigation: Desktop sidebar, tablet drawer, mobile hamburger */}
      <ResponsiveWrapper behavior="Navigation">
        <Navigation />
      </ResponsiveWrapper>

      {/* Content: Responsive margins, spacing, and mobile optimizations */}
      <ResponsiveWrapper behavior="Content">
        <div style={{ maxWidth: '1200px', padding: '2rem' }}>
          {/* ResponsiveWrapper overrides these styles based on screen size */}
        </div>
      </ResponsiveWrapper>

      {/* Header: Responsive positioning and spacing */}
      <ResponsiveWrapper behavior="Header">
        <Header />
      </ResponsiveWrapper>
    </ResponsiveProvider>
  );
}

2. Responsive Hooks (Manual Control)

import { useBreakpoint, useIsMobile, useOrientation } from '@flowlabkit/ui';

function CustomResponsiveComponent() {
  const isMobile = useIsMobile();
  const breakpoint = useBreakpoint();
  const orientation = useOrientation();
  
  return (
    <div style={{
      padding: isMobile ? '1rem' : '2rem',
      maxWidth: breakpoint === 'xs' ? '100%' : '1200px',
      flexDirection: orientation === 'portrait' ? 'column' : 'row'
    }}>
      <h1>Breakpoint: {breakpoint}</h1>
      <p>Mobile: {isMobile ? 'Yes' : 'No'}</p>
      <p>Orientation: {orientation}</p>
    </div>
  );
}

3. Hardcoded CSS (Static)

// Traditional approach - no responsiveness
<div style={{ padding: '2rem', maxWidth: '1200px' }}>
  Static content
</div>

Responsive Features

• Real-Time Updates: All hooks update immediately on window resize
• Mobile-First Design: Optimized for touch interactions and small screens
• Unified Layout Components: NavigationLayout, ContentLayout, HeaderLayout handle all screen sizes internally
• CSS-Like Override System: ResponsiveWrapper always takes precedence over wrapped component styles
• Accessibility: Full ARIA support, keyboard navigation, screen reader friendly
• TypeScript Support: Complete type safety with comprehensive interfaces

Breakpoints

• xs: 0-479px (Mobile portrait)
• sm: 480-639px (Mobile landscape)
• md: 640-767px (Small tablet)
• lg: 768-1023px (Tablet/small desktop)
• xl: 1024-1279px (Desktop)
• xxl: 1280px+ (Large desktop)

Full Responsive Documentation →

Quick Start

Basic Setup

Default Light/Dark Mode

import React from 'react';
import { ThemeProvider } from '@flowlabkit/ui';

function App() {
  return (
    <ThemeProvider initialConfig={{ mode: 'dark', fontSize: 'medium' }}>
      <YourAppContent />
    </ThemeProvider>
  );
}

Custom Theme Override

import React from 'react';
import { ThemeProvider } from '@flowlabkit/ui';
import { oceanTheme, cyberpunkTheme } from '@flowlabkit/ui/themes';

function App() {
  return (
    <ThemeProvider 
      lightTheme={oceanTheme}
      darkTheme={cyberpunkTheme}
      onThemeChange={(info) => {
        console.log(`Switched to ${info.themeName} in ${info.mode} mode`);
      }}
    >
      <YourAppContent />
    </ThemeProvider>
  );
}

Theme Switching

import { themes, allThemes } from '@flowlabkit/ui/themes';

function ThemeSelector({ onThemeChange }) {
  return (
    <div>
      {allThemes.map(themeName => (
        <button
          key={themeName}
          onClick={() => onThemeChange(themes[themeName])}
        >
          {themeName.charAt(0).toUpperCase() + themeName.slice(1)}
        </button>
      ))}
    </div>
  );
}

Using the Theme Hook

import { useTheme } from '@flowlabkit/ui';

function ThemedComponent() {
  const { theme, themeName, config, toggleTheme, setMode } = useTheme();
  
  return (
    <div style={{
      backgroundColor: theme.colors.background.app,
      color: theme.colors.text.primary,
      padding: theme.spacing.lg,
    }}>
      <h1>Theme: {themeName}</h1>
      <p>Mode: {config.mode}</p>
      <button onClick={toggleTheme}>
        Toggle Light/Dark
      </button>
      <button onClick={() => setMode('light')}>
        Light Mode
      </button>
      <button onClick={() => setMode('dark')}>
        Dark Mode
      </button>
    </div>
  );
}

Theme Selection Component

import { useTheme } from '@flowlabkit/ui';
import { themes } from '@flowlabkit/ui/themes';

function ThemeSelector() {
  const { themeName, config, toggleTheme } = useTheme();
  
  return (
    <div>
      <h3>Current: {themeName} ({config.mode} mode)</h3>
      <button onClick={toggleTheme}>
        Switch to {config.mode === 'light' ? 'dark' : 'light'}
      </button>
    </div>
  );
}

Import Options (Tree-Shaking)

After running npm install @flowlabkit/ui, choose your import strategy:

Full Import (Easiest)

import { ThemeProvider, Button, Card, oceanTheme } from '@flowlabkit/ui';

function App() {
  return (
    <ThemeProvider initialConfig={{ mode: 'dark' }}>
      <Card>
        <Button>Hello World</Button>
      </Card>
    </ThemeProvider>
  );
}

Minimal Import (Smallest Bundle)

import { ThemeProvider, lightTheme, darkTheme } from '@flowlabkit/ui/core';

function MinimalApp() {
  return (
    <ThemeProvider lightTheme={lightTheme} darkTheme={darkTheme}>
      <div style={{ 
        backgroundColor: 'var(--bg-app)', 
        color: 'var(--text-primary)' 
      }}>
        <h1>Just themes, no components</h1>
      </div>
    </ThemeProvider>
  );
}

Custom Mix

// Core + specific themes + select components
import { ThemeProvider } from '@flowlabkit/ui/core';
import { oceanTheme, cyberpunkTheme } from '@flowlabkit/ui/themes';
import { Button, Card } from '@flowlabkit/ui/components';

function CustomApp() {
  return (
    <ThemeProvider lightTheme={oceanTheme} darkTheme={cyberpunkTheme}>
      <Card>
        <Button>Perfect bundle optimization!</Button>
      </Card>
    </ThemeProvider>
  );
}

Using CSS Variables

The theme system automatically applies CSS variables to the document root. Use them in your CSS:

.my-component {
  background-color: var(--bg-surface);
  color: var(--text-primary);
  border: 1px solid var(--border-color);
  border-radius: var(--radius-md);
  padding: var(--space-md);
  font-size: var(--font-size-base);
}

.primary-button {
  background-color: var(--accent-500);
  color: var(--text-on-accent);
  border-radius: var(--radius-sm);
  padding: var(--space-sm) var(--space-md);
}

.primary-button:hover {
  background-color: var(--accent-600);
}

API Reference

ThemeProvider Props

interface ThemeProviderProps {
  children: ReactNode;
  initialConfig?: Partial<ThemeConfig>;
  persistToLocalStorage?: boolean;
  localStorageKey?: string;
}

useTheme Hook

interface UseThemeReturn {
  theme: Theme;
  config: ThemeConfig;
  setMode: (mode: 'light' | 'dark') => void;
  setFontSize: (fontSize: 'small' | 'medium' | 'large') => void;
  setCompactMode: (compact: boolean) => void;
}

Theme Configuration

interface ThemeConfig {
  mode: 'light' | 'dark';
  fontSize: 'small' | 'medium' | 'large';
  compactMode: boolean;
}

Available CSS Variables

Colors

Gray Scale (50-950)

• --gray-50 through --gray-950: Complete gray color scale

Accent Colors (50-950)

• --accent-50 through --accent-950: Brand/accent color scale

Semantic Colors

• --success, --success-light: Success states
• --error, --error-light: Error states
• --warning, --warning-light: Warning states
• --info, --info-light: Info states

Background Colors

• --bg-app: Main application background
• --bg-surface: Card/surface backgrounds
• --bg-elevated: Elevated surface backgrounds
• --bg-navbar: Navigation bar background
• --bg-sidebar: Sidebar background
• --bg-hover: Hover state background
• --bg-active: Active state background

Text Colors

• --text-primary: Primary text color
• --text-secondary: Secondary text color
• --text-tertiary: Tertiary text color
• --text-disabled: Disabled text color
• --text-accent: Accent text color
• --text-on-accent: Text on accent backgrounds

Button Colors

• --btn-bg, --btn-bg-hover, --btn-bg-active: Default button states
• --btn-primary-bg, --btn-primary-bg-hover: Primary button states
• --btn-disabled-bg: Disabled button background

Spacing

• --space-xs (4px): Extra small spacing
• --space-sm (8px): Small spacing
• --space-md (16px): Medium spacing
• --space-lg (24px): Large spacing
• --space-xl (32px): Extra large spacing
• --space-2xl (48px): 2X large spacing

Typography

Font Sizes

• --font-size-xs through --font-size-3xl: Complete font size scale
• --font-weight-normal through --font-weight-bold: Font weight options

Layout

Border Radius

• --radius-sm (4px): Small radius
• --radius-md (8px): Medium radius
• --radius-lg (12px): Large radius
• --radius-full (9999px): Full/pill radius

Shadows

• --shadow-xs through --shadow-xl: Shadow scale for depth

Z-Index

• --z-dropdown (1000): Dropdown elements
• --z-sticky (1020): Sticky elements
• --z-overlay (1030): Overlay elements
• --z-modal (1040): Modal dialogs
• --z-toast (1050): Toast notifications

Transitions

• --transition-fast (150ms): Fast transitions
• --transition-base (200ms): Base transition speed
• --transition-slow (300ms): Slow transitions

Advanced Usage

Manual CSS Variable Application

import { themeToCSSVariables, applyCSSVariables } from '@flowlabkit/ui';

// Apply theme variables manually
const variables = themeToCSSVariables(theme, config);
applyCSSVariables(variables);

Custom Theme Creation

import { Theme, lightTheme } from '@flowlabkit/ui';

const customTheme: Theme = {
  ...lightTheme,
  colors: {
    ...lightTheme.colors,
    accent: {
      ...lightTheme.colors.accent,
      500: '#your-brand-color',
    }
  }
};

Browser Support

• Modern browsers with CSS Custom Properties support
• React 16.8+ (hooks required)
• TypeScript 4.0+ recommended

Live Demo & Documentation

View Interactive Showcase →

Experience all themes, components, and features with live examples and complete documentation.

Development

# Run the interactive showcase locally
npm run showcase

# Build showcase for production
npm run showcase:build

# Build the package
npm run build

Migration from CSS Variables

If you're migrating from a CSS variable-based theme system:

1. Install the package
2. Wrap your app in ThemeProvider
3. Replace manual CSS variable definitions with theme system
4. Use the provided CSS variables in your stylesheets
5. Add theme controls using the useTheme hook

Contributing

See the main FlowLabKit repository for contribution guidelines.

Repository

Source Code →

FlowLabKit Ecosystem

This package is part of FlowLabKit - a comprehensive toolkit for building modern React applications:

| Package | Purpose | Status | |---------|---------|--------| | @flowlabkit/ui | Theme system with 8 built-in themes | ✅ Available | | create-flowlabkit-app | Interactive project installer | ✅ Available | | @flowlabkit/components | Complete UI component library | 🚧 Coming soon | | @flowlabkit/icons | Icon library | 🚧 Coming soon | | @flowlabkit/animations | Animation utilities | 🚧 Coming soon | | @flowlabkit/forms | Form handling toolkit | 🚧 Coming soon |

Quick Install

Get started with FlowLabKit UI in seconds:

# 🚀 Interactive installer (recommended)
npm create flowlabkit-app@latest my-app

# 📦 Add to existing project  
npm install @flowlabkit/ui

Installer Features:

• Interactive theme selection (choose from 8 themes)
• Multiple templates (React TypeScript/JavaScript, Vanilla)
• Component library options (full components or themes-only)
• Pre-configured Vite development environment
• Working examples and responsive demos included

License

MIT