@true-tech-team/ui-components

A comprehensive React component library built with TypeScript, SCSS Modules, and featuring a robust theming system with dark/light mode support.

Features

• 🎨 Comprehensive Theming - 37 color families with 10 shades each (370+ colors)
• 🌓 Dark/Light Mode - Built-in theme switching with CSS variables
• 📏 4px Grid System - Consistent spacing throughout
• 🎯 Type-Safe - Full TypeScript support with comprehensive types
• 🧩 Component Library - Reusable, customizable components
• 🎭 Icon System - SVG-based icons with easy customization
• 🛠️ Utility Classes - 500+ utility classes for rapid development
• 📦 Tree-Shakeable - Optimized bundle sizes
• ♿ Accessible - Built with accessibility in mind

Installation

npm install @true-tech-team/ui-components

Quick Start

Wrap your app with GlobalProvider

import { GlobalProvider } from '@true-tech-team/ui-components';

function App() {
  return (
    <GlobalProvider themeConfig={{ mode: 'light' }}>
      <YourApp />
    </GlobalProvider>
  );
}

Use components

import { Button, Icon } from '@true-tech-team/ui-components';

function MyComponent() {
  return (
    <div>
      <Button variant="primary" size="md">
        Click me
      </Button>

      <Button variant="outline" startIcon={<Icon name="check" size={16} />}>
        Save
      </Button>
    </div>
  );
}

Components

Buttons

Button

Versatile button component with multiple variants and sizes.

<Button variant="primary" size="md" onClick={() => console.log('clicked')}>
  Click me
</Button>

<Button variant="outline" startIcon={<Icon name="check" />}>
  With Icon
</Button>

Variants: primary, secondary, outline, ghost Sizes: sm, md, lg

IconButton

Button component optimized for icon-only display.

<IconButton aria-label="Close" size="md">
  <Icon name="close" />
</IconButton>

Display

Icon

SVG-based icon system with customizable size and color.

<Icon name="check" size={24} color="var(--theme-primary)" />

Available icons: chevron-down, chevron-up, chevron-left, chevron-right, close, check, info, warning, error, eye, eye-off, user, users, building, dollar, chart-line, chart-bar, trending-down, and more

Avatar

User profile avatars with image, initials, and icon variants.

<Avatar src="/path/to/image.jpg" alt="User name" size="md" />
<Avatar initials="JD" size="lg" />
<Avatar icon={<Icon name="user" />} variant="secondary" />

Sizes: xs, sm, md, lg, xl Variants: primary, secondary, tertiary

Badge

Notification badges with count display.

<Badge count={5} variant="primary" />
<Badge count={99} max={99} variant="error" />

Chip

Interactive chips for tags and selections.

<Chip label="React" onDelete={() => {}} />
<Chip label="TypeScript" variant="outlined" />

Pill

Status and category pills.

<Pill label="Active" variant="success" />
<Pill label="Pending" variant="warning" />

Tag

Labeling and categorization tags.

<Tag>New</Tag>
<Tag variant="success">Available</Tag>

StatusIndicator

Status indicator dots with labels.

<StatusIndicator status="online" label="Online" />
<StatusIndicator status="offline" label="Offline" />

ProgressBar

Linear progress bars with labels and variants.

<ProgressBar value={75} max={100} variant="primary" />
<ProgressBar value={50} label="50%" showLabel />

CircularProgress

Circular progress indicators.

<CircularProgress value={75} size={64} />
<CircularProgress indeterminate size={48} />

Skeleton

Loading skeleton screens for content placeholders.

<Skeleton variant="text" width="100%" />
<Skeleton variant="circular" width={40} height={40} />
<Skeleton variant="rectangular" width={200} height={100} />

KPI

Key Performance Indicator display component.

<KPI
  value="$45,231"
  label="Total Revenue"
  trend={12.5}
  trendDirection="up"
  icon={<Icon name="dollar" />}
/>

Stat

Statistical display component for metrics.

<Stat label="Total Users" value="1,234" change="+12.5%" changeType="increase" />

List

Comprehensive list component with selection, virtualization, and keyboard navigation.

<List
  items={users}
  renderItem={(user) => (
    <ListItem
      key={user.id}
      primary={user.name}
      secondary={user.email}
      icon={<Icon name="user" />}
    />
  )}
  selectable
  onSelectionChange={(selected) => console.log(selected)}
/>

Table

Data table component with sorting, selection, and pagination.

<Table
  data={users}
  columns={[
    { key: 'name', header: 'Name', sortable: true },
    { key: 'email', header: 'Email' },
    { key: 'role', header: 'Role', sortable: true },
  ]}
  selectable
  pagination={{ pageSize: 10 }}
  onSort={(key, direction) => console.log(key, direction)}
/>

Drag and Drop

SortableList

Reorderable list with drag-and-drop functionality.

<DndProvider>
  <SortableList
    items={items}
    onReorder={(newOrder) => setItems(newOrder)}
    renderItem={(item) => (
      <div>
        <DragHandle />
        {item.label}
      </div>
    )}
  />
</DndProvider>

SortableGrid

Reorderable grid layout with drag-and-drop.

<DndProvider>
  <SortableGrid
    items={gridItems}
    columns={3}
    onReorder={(newOrder) => setGridItems(newOrder)}
    renderItem={(item) => <Card>{item.content}</Card>}
  />
</DndProvider>

KanbanBoard

Kanban-style board with draggable cards between columns.

<DndProvider>
  <KanbanBoard
    columns={[
      { id: 'todo', title: 'To Do', items: todoItems },
      { id: 'progress', title: 'In Progress', items: progressItems },
      { id: 'done', title: 'Done', items: doneItems },
    ]}
    onCardMove={(cardId, fromColumn, toColumn) => handleMove(cardId, fromColumn, toColumn)}
  />
</DndProvider>

ResizablePanels

Resizable panel layouts for split views.

<ResizablePanels direction="horizontal">
  <Panel defaultSize={30} minSize={20}>
    <Sidebar />
  </Panel>
  <Panel>
    <MainContent />
  </Panel>
</ResizablePanels>

Filters

Filter System

Comprehensive filtering system with various field types and layouts.

<FilterProvider filters={filters} onChange={(filters) => console.log(filters)}>
  <FilterBar>
    <TextFilter field="name" label="Name" />
    <SelectFilter
      field="status"
      label="Status"
      options={[
        { value: 'active', label: 'Active' },
        { value: 'inactive', label: 'Inactive' },
      ]}
    />
    <DateRangeFilter field="createdAt" label="Created" />
    <NumberRangeFilter field="price" label="Price" min={0} max={1000} />
  </FilterBar>
</FilterProvider>

Inputs

Input

Text input with validation, formatting, and various configurations.

<Input
  label="Email"
  type="email"
  placeholder="Enter your email"
  validation={(value) =>
    value.includes('@') ? { valid: true } : { valid: false, message: 'Invalid email' }
  }
/>

Autocomplete

Input with dropdown suggestions and filtering.

<Autocomplete
  options={[
    { value: '1', label: 'Option 1' },
    { value: '2', label: 'Option 2' },
  ]}
  placeholder="Search..."
/>

Select

Dropdown select component with search and custom rendering.

<Select
  options={[
    { value: 'us', label: 'United States' },
    { value: 'ca', label: 'Canada' },
  ]}
  placeholder="Select country"
/>

Checkbox

Checkbox input with labels and indeterminate state.

<Checkbox label="Accept terms" checked={accepted} onChange={setAccepted} />

Radio & RadioGroup

Radio button inputs with group management.

<RadioGroup value={selected} onChange={setSelected}>
  <Radio value="option1" label="Option 1" />
  <Radio value="option2" label="Option 2" />
</RadioGroup>

Toggle

Switch/toggle component for boolean states.

<Toggle checked={enabled} onChange={setEnabled} label="Enable feature" />

Textarea

Multi-line text input with auto-resize.

<Textarea label="Description" placeholder="Enter description" rows={4} maxLength={500} />

NumberInput

Numeric input with increment/decrement controls.

<NumberInput label="Quantity" min={0} max={100} step={1} value={quantity} onChange={setQuantity} />

PhoneInput

International phone number input with country selection.

<PhoneInput value={phone} onChange={setPhone} defaultCountry="US" />

Slider

Range slider with marks and custom formatting.

<Slider min={0} max={100} value={volume} onChange={setVolume} marks={[0, 25, 50, 75, 100]} />

Rating

Star rating input component.

<Rating value={rating} onChange={setRating} max={5} />

TagInput

Input for managing multiple tags.

<TagInput tags={tags} onChange={setTags} placeholder="Add tag..." />

FilePicker

File upload component with drag-and-drop support.

<FilePicker
  accept=".pdf,.doc,.docx"
  maxSize={5 * 1024 * 1024}
  onChange={(files) => console.log(files)}
/>

ColorPicker

Color selection with multiple format support (hex, rgb, hsl).

<ColorPicker value={color} onChange={setColor} format="hex" />

DatePicker

Single date selection with calendar interface.

<DatePicker value={date} onChange={setDate} minDate={new Date()} />

DateRangePicker

Date range selection with presets.

<DateRangePicker
  startDate={startDate}
  endDate={endDate}
  onChange={(start, end) => {
    setStartDate(start);
    setEndDate(end);
  }}
  presets={[{ label: 'Last 7 days', value: { start: -7, end: 0 } }]}
/>

Overlays

Portal

Render children in a different part of the DOM.

<Portal>
  <div>This renders at document.body</div>
</Portal>

Popover

Floating content positioned relative to a trigger.

<Popover trigger={<Button>Open Popover</Button>} content={<div>Popover content</div>} />

Tooltip

Hover tooltip with customizable positioning.

<Tooltip content="Helpful information" position="top">
  <Button>Hover me</Button>
</Tooltip>

Dropdown

Dropdown menu with trigger and content.

<Dropdown
  trigger={<Button>Options</Button>}
  content={
    <MenuList>
      <MenuItem>Action 1</MenuItem>
      <MenuItem>Action 2</MenuItem>
    </MenuList>
  }
/>

Menu

Flexible menu system with items, groups, and dividers.

<Menu>
  <MenuList>
    <MenuItem onClick={() => console.log('Edit')}>Edit</MenuItem>
    <MenuItem onClick={() => console.log('Delete')}>Delete</MenuItem>
    <MenuDivider />
    <MenuGroup label="More options">
      <MenuItem>Settings</MenuItem>
    </MenuGroup>
  </MenuList>
</Menu>

Navigation

Stepper

Multi-step progress indicator for wizard-like interfaces.

<Stepper activeStep={1}>
  <Step label="Account" description="Create your account" />
  <Step label="Profile" description="Set up your profile" />
  <Step label="Review" description="Review and submit" />
</Stepper>

Breadcrumbs

Navigation breadcrumb trail for hierarchical page structure.

<Breadcrumbs>
  <BreadcrumbItem href="/">Home</BreadcrumbItem>
  <BreadcrumbItem href="/products">Products</BreadcrumbItem>
  <BreadcrumbItem>Current Page</BreadcrumbItem>
</Breadcrumbs>

Navbar

Responsive navigation bar with collapsible menu support.

<Navbar>
  <NavbarBrand>My App</NavbarBrand>
  <NavbarToggle />
  <NavbarCollapse>
    <NavbarNav>
      <NavLink href="/">Home</NavLink>
      <NavLink href="/about">About</NavLink>
    </NavbarNav>
    <NavbarActions>
      <Button>Sign In</Button>
    </NavbarActions>
  </NavbarCollapse>
</Navbar>

SideNav

Sidebar navigation with groups, items, and dividers.

<SideNav>
  <SideNavGroup label="Main">
    <SideNavItem icon={<Icon name="home" />} href="/">
      Dashboard
    </SideNavItem>
    <SideNavItem icon={<Icon name="users" />} href="/users">
      Users
    </SideNavItem>
  </SideNavGroup>
  <SideNavDivider />
  <SideNavItem icon={<Icon name="settings" />} href="/settings">
    Settings
  </SideNavItem>
</SideNav>

Pagination

Page navigation with customizable controls.

<Pagination currentPage={page} totalPages={10} onPageChange={setPage} showFirstLast />

BottomNavigation

Mobile-friendly bottom navigation bar.

<BottomNavigation value={tab} onChange={setTab}>
  <BottomNavigationItem icon={<Icon name="home" />} label="Home" value="home" />
  <BottomNavigationItem icon={<Icon name="search" />} label="Search" value="search" />
  <BottomNavigationItem icon={<Icon name="user" />} label="Profile" value="profile" />
</BottomNavigation>

Tabs

Tabbed content navigation.

<Tabs defaultValue="tab1">
  <TabList>
    <Tab value="tab1">Tab 1</Tab>
    <Tab value="tab2">Tab 2</Tab>
  </TabList>
  <TabPanel value="tab1">Content 1</TabPanel>
  <TabPanel value="tab2">Content 2</TabPanel>
</Tabs>

Layout

Panes

Resizable split pane layouts.

<Panes direction="horizontal">
  <Pane minSize={200}>Left Panel</Pane>
  <Pane>Right Panel</Pane>
</Panes>

ResponsiveStack

Stack layout that adapts to screen size.

<ResponsiveStack breakpoint={768} spacing={4}>
  <Card>Item 1</Card>
  <Card>Item 2</Card>
</ResponsiveStack>

AdaptiveGrid

Auto-adjusting grid layout based on container width.

<AdaptiveGrid minItemWidth={250} gap={16}>
  <Card>Item 1</Card>
  <Card>Item 2</Card>
  <Card>Item 3</Card>
</AdaptiveGrid>

MasonryLayout

Pinterest-style masonry grid for variable-height items.

<MasonryLayout columns={3} gap={16}>
  <Card>Short content</Card>
  <Card>Much longer content that takes more space</Card>
  <Card>Medium content</Card>
</MasonryLayout>

Forms

FormBuilder

Dynamic form builder with validation and state management.

<FormBuilder
  fields={[
    {
      name: 'email',
      label: 'Email',
      type: 'email',
      required: true,
      validation: { pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ },
    },
    {
      name: 'password',
      label: 'Password',
      type: 'password',
      required: true,
    },
  ]}
  onSubmit={(values) => console.log(values)}
/>

Theming

Theme Configuration

The library includes a comprehensive theming system with 37 color families and 10 shades each, providing 370+ colors out of the box.

import { GlobalProvider } from '@true-tech-team/ui-components';

function App() {
  return (
    <GlobalProvider
      themeConfig={{
        mode: 'light',
        // Optional: override theme values
        overrides: {
          colors: {
            primary: '#007bff',
          },
        },
      }}
    >
      <YourApp />
    </GlobalProvider>
  );
}

Toggle Theme

import { useTheme } from '@true-tech-team/ui-components';

function ThemeToggle() {
  const { mode, toggleMode } = useTheme();
  return <button onClick={toggleMode}>Current: {mode}</button>;
}

CSS Variables

All theme values are exposed as CSS variables for easy customization:

.custom-element {
  color: var(--theme-primary);
  background: var(--theme-surface);
  border-radius: var(--theme-radius-md);
  padding: var(--theme-spacing-4);
}

Utility Classes

Spacing (4px grid):

<div class="m-4 p-2">Margin 16px, Padding 8px</div>
<div class="mt-2 mb-4 px-6">Margin top 8px, bottom 16px, padding x 24px</div>

Flexbox:

<div class="flex items-center justify-between gap-4">...</div>
<div class="flex-col items-start">...</div>

Grid:

<div class="grid grid-cols-3 gap-4">...</div>

Colors:

<div class="bg-primary text-on-primary">...</div>
<div class="bg-surface text-on-surface">...</div>

Typography:

<h1 class="text-2xl font-bold">Heading</h1>
<p class="text-sm text-secondary">Small text</p>

Utility Functions

Theme Utils

import { getThemeValue, setThemeValue, pxToRem, gridSpacing } from '@true-tech-team/ui-components';

// Get theme values
const primaryColor = getThemeValue('--theme-primary');

// Convert pixels to rem
const remValue = pxToRem(16); // '1rem'

// Grid-based spacing
const spacing = gridSpacing(4); // '16px' (4 * 4px grid)

Color Utils

import { hexToRgb, rgbToHsl, isLightColor, getBrightness } from '@true-tech-team/ui-components';

const rgb = hexToRgb('#ff0000'); // { r: 255, g: 0, b: 0 }
const hsl = rgbToHsl(255, 0, 0); // { h: 0, s: 100, l: 50 }
const isLight = isLightColor('#ffffff'); // true

Date Utils

import { formatDate, getDaysInMonth, isDateInRange, addDays } from '@true-tech-team/ui-components';

const formatted = formatDate(new Date(), 'YYYY-MM-DD');
const daysInMonth = getDaysInMonth(2024, 0); // January 2024
const inRange = isDateInRange(date, startDate, endDate);
const futureDate = addDays(new Date(), 7);

Validation Utils

import { validators, combineValidators } from '@true-tech-team/ui-components';

const emailValidator = validators.email();
const requiredValidator = validators.required('This field is required');
const combined = combineValidators([requiredValidator, emailValidator]);

const result = combined('[email protected]');

Development

Building

# Build library for production
nx build ui-components --configuration=production

# Build for development
nx build ui-components --configuration=development

The build output will be in dist/libs/ui-components/.

Testing

# Run tests
nx test ui-components

# Run tests in watch mode
nx test ui-components --watch

# Run tests with coverage
nx test ui-components --coverage

Linting

# Lint
nx lint ui-components

# Lint and fix
nx lint ui-components --fix

Storybook

View and interact with all components in Storybook:

# Start Storybook dev server
nx storybook ui-components

# Build Storybook static site
nx build-storybook ui-components

Storybook will be available at http://localhost:6006.

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

TypeScript

This library is written in TypeScript and includes type definitions. All components, props, and utilities are fully typed for the best development experience.

Contributing

Contributions are welcome! Please ensure all tests pass and follow the existing code style.

Repository

True Tech Team UI Components Github

Storybook

True Tech Team React Components

License

MIT