@consolia/ui NPM

@consolia/ui

A React component library styled with Stitches, designed specifically for Consolia's internal projects and design system.

⚠️ Important Notice

This library is built specifically for Consolia's design system and internal use cases. While it's open-sourced for transparency and potential inspiration, it's not intended as a general-purpose component library for public consumption.

✅ Use if: You're working on Consolia projects or want to study the implementation
❌ Consider alternatives if: You need a general-purpose UI library for your own projects

For general-purpose React component libraries, consider Chakra UI, Mantine, Ant Design, or Material-UI instead.

Features

🎨 Modern Design System - Carefully crafted components with consistent theming
🏗️ Built for Next.js - Compatible with Next.js and React 19+
🎯 TypeScript First - Full type safety with comprehensive TypeScript definitions
📱 Responsive - Mobile-first design with flexible breakpoint system
🎭 Theming - Light/dark mode support with Stitches CSS-in-JS
⚡ Performance - Tree-shakeable with minimal runtime overhead
📖 Well Documented - Auto-generated API documentation from TypeScript interfaces

Installation

# Using pnpm (recommended)
pnpm add @consolia/ui

# Using npm
npm install @consolia/ui

# Using yarn
yarn add @consolia/ui

Peer Dependencies

Ensure you have the required peer dependencies:

pnpm add react react-dom next

Quick Start

import { Provider, Button, Text, Stack } from '@consolia/ui';

function App() {
  return (
    <Provider>
      <Stack direction="column" align="center" css={{ padding: '$large' }}>
        <Text as="h1">Welcome to Consolia UI</Text>
        <Button theme="solid" onClick={() => alert('Hello!')}>
          Get Started
        </Button>
      </Stack>
    </Provider>
  );
}

Development

To work on components locally:

# Install dependencies
pnpm install

# Start development server
pnpm dev

# Run linting and formatting
pnpm tidy

# Build the library
pnpm build

# Generate documentation
pnpm docs:only

Project Structure

src/
├── components/          # React components
├── hooks/              # Custom React hooks
├── types.ts            # TypeScript interfaces (auto-documented)
├── stitches.config.ts  # Design system configuration
└── index.ts            # Main entry point

docs/                   # Auto-generated API documentation
playground/             # Component demos and examples

Components

This library includes the following components with full TypeScript support and comprehensive documentation:

Accordion - Collapsible content sections with multiple expansion support
Avatar - User profile image with fallback text display
Badge - Small status indicators and informational labels
Box - Versatile container with optional image, header, and footer
Button - Interactive element for user actions with multiple themes
Calendar - Date picker with range and single selection modes
CalendarMonths - Month and year selection interface
Divider - Visual separator line with customizable spacing
Drawer - Slide-out panel overlay for secondary content
Field - Multi-line textarea input with validation and actions
Form - Form wrapper with validation and submission handling
Icon - Consistent icon wrapper with theming support
Image - Enhanced Next.js Image with additional styling options
Input - Single-line form input with validation and actions
Loading - Animated loading spinner with customizable appearance
LoadingOverlay - Full-screen loading overlay with message display
Logo - Consolia brand logo in various formats and styles
Menu - Dropdown menu with nested options and keyboard navigation
Modal - Centered overlay dialog for important interactions
Nodes - Hierarchical node tree visualization with connecting lines
Popover - Floating content overlay triggered by user interaction
Portal - Render content outside normal DOM hierarchy
Provider - Theme and context provider for the entire UI system
Select - Dropdown selection with filtering and positioning options
SelectMulti - Multi-selection dropdown with limits and batch operations
Stack - Responsive layout container with flexible spacing and alignment
Table - Data table with sorting, pagination, and nested rows
Tabs - Tabbed interface for organizing content into panels
Text - Versatile text element with multiple sizes, styles, and link support
Upload - File upload with drag & drop, validation, and progress
View - Main layout container with hero styling and responsive behavior

📖 Full API Documentation: Detailed TypeScript interfaces, props, and examples are available in the docs/interfaces/ directory. All documentation is auto-generated from TSDoc comments in the source code.

Theming

The library uses Stitches for styling with a comprehensive design system:

import { Provider } from '@consolia/ui';

// Enable dark mode
<Provider dark>
  <YourApp />
</Provider>

// Custom CSS with theme tokens
<Button css={{ 
  backgroundColor: '$purple', 
  color: '$background',
  borderRadius: '$large' 
}}>
  Custom Button
</Button>

Available Theme Tokens

Colors: $background, $text, $purple, $blue, $orange, $yellow, $border, $borderLight, $overlay, $surface, $surfaceHover, $surfaceLight
Spacing: $none, $smallest, $smaller, $small, $medium, $large, $larger, $largest, $excess
Radii: $small, $medium, $large
Font Sizes: $small, $default, $h6, $h5, $h4, $h3, $h2, $h1
Breakpoints: phone, phoneX, tablet, tabletX, laptop, laptopX, desktop, desktopX, wide

Available Utils

Responsive: phone(), phoneX(), tablet(), tabletX(), laptop(), laptopX(), desktop(), desktopX(), wide(), micro(), print(), retina()
Visibility: hidden(), hiddenInline(), hiddenSpecial(), visible(), visibleInline(), visibleSpecial()
Theme-aware: darkOnly(), lightOnly()

// Example usage of utils
<Button css={{
  phone: { fontSize: '$small' },      // Responsive
  hidden: 'tablet',                   // Hide on tablet
  darkOnly: { color: '$yellow' }  // Dark mode specific
}}>
  Responsive Button
</Button>